apps 0.0.1-beta.8 → 0.0.1-beta.81

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-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,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 {};

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

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

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

@@ -1,11 +1,32 @@
 import { Schema } from "effect";
 import { JsonObject } from "../contracts/schema.js";
-/** Resolve OpenAPI objects once with Swagger; 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.
+/**
+ * An object in a document that was validated as JSON when it was read. Compilation only turns JSON
+ * into JSON, so inside it an object's shape is checked, not its every leaf again: re-validating
+ * whole documents was most of a large API's compile time.
  */
-export declare function openApiDocument(input: unknown): Promise<{
+export declare const DocumentObject: Schema.declare<{
+    readonly [x: string]: Schema.Json;
+}, {
+    readonly [x: string]: Schema.Json;
+}>;
+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 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: {
         readonly openapi: string;
         readonly paths: {
@@ -13,39 +34,45 @@ export declare function openApiDocument(input: unknown): Promise<{
                 readonly [x: string]: Schema.Json;
             };
         };
-        readonly security?: readonly {
-            readonly [x: string]: readonly string[];
-        }[];
-        readonly servers?: readonly {
-            readonly url: string;
-            readonly variables?: {
-                readonly [x: string]: Schema.Json;
-            };
-        }[];
         readonly components?: {
-            readonly securitySchemes?: {
+            readonly schemas?: {
                 readonly [x: string]: {
                     readonly [x: string]: Schema.Json;
                 };
             };
-            readonly schemas?: {
+            readonly securitySchemes?: {
                 readonly [x: string]: {
                     readonly [x: string]: Schema.Json;
                 };
             };
         };
+        readonly security?: readonly {
+            readonly [x: string]: readonly string[];
+        }[];
+        readonly servers?: readonly {
+            readonly url: string;
+            readonly variables?: {
+                readonly [x: string]: Schema.Json;
+            };
+        }[];
     };
     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-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";
@@ -6,12 +7,19 @@ import { OpenapiError, type CredentialBinding, type OpenapiOperation, type Opena
 type DeclaredError = OpenapiErrorResponse & {
     readonly decoder: Schema.Decoder<Schema.Json>;
 };
+/** What decides whether an account can call an operation: its transport and security. */
+export interface OpenapiOperationAccess {
+    readonly streaming?: true;
+    readonly request: {
+        readonly security: OpenapiOperation["request"]["security"];
+    };
+}
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
-    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
+    available: (op: OpenapiOperationAccess, account: OpenapiAccount | undefined) => boolean;
+    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/openapi-source.d.ts

@@ -3,6 +3,7 @@ import { Duration } from "effect";
 import type { AppCache } from "../contracts/cache.js";
 import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
 import { JsonObject, JsonValue } from "../contracts/schema.js";
+import { type OpenapiToolNames } from "../contracts/openapi-compile.js";
 import { type OperationKinds } from "./protocol-operations.js";
 import { type RouterDeclaration } from "./router.js";
 /** Static credential placement and destination are reviewed when the app is authored/imported. */
@@ -16,6 +17,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;
     /**
@@ -34,3 +41,14 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
 export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
 /** No I/O during app construction. All accounts share credential-free compilation. */
 export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;
+/** The settings `openapiToolNames` reads: the router's, without an account or cache. */
+export type OpenapiToolNamesOptions = Omit<OpenapiSourceOptions, "cache" | "account" | "parameterDefaults" | "freshFor" | "staleFor">;
+/**
+ * The tools `liveOpenapiRouter` with the same options exposes, from the definition alone: no
+ * account, cache or deployment. Each tool says which `methods` and `oauth` entries expose it, so
+ * an author can check the names a `withApprovals` policy matches before any account connects.
+ * `skipped` lists only the operations the compiler left out and why. An operation no configured
+ * `methods` or `oauth` entry can authorize is missing from `tools` and not listed in `skipped`.
+ * `fetch` defaults to the global fetch.
+ */
+export declare const openapiToolNames: (options: OpenapiToolNamesOptions) => Promise<OpenapiToolNames>;

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

@@ -0,0 +1,4 @@
+type Node = Record<string, unknown>;
+/** Upgrade a 3.0 document the caller owns. Any other version is returned unchanged. */
+export declare const upgradeOpenApi30InPlace: (document: Node) => Node;
+export {};

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

@@ -1,5 +1,5 @@
 /** Pure operation declarations. Only the author callback crosses the Promise boundary. */
-import { Effect, Schema as EffectSchema } from "effect";
+import { Schema as EffectSchema } from "effect";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppContext, QueryContext, MutationContext } from "../contracts/context.js";
 import type { Approval } from "../approval.js";
@@ -38,6 +38,11 @@ export interface RouterChild<Query, Mutation> {
     readonly [QueryHandlerContext]?: (context: Query) => void;
     readonly [MutationHandlerContext]?: (context: Mutation) => void;
 }
+/**
+ * A query or mutation whose handler context is checked by its kind, as a dynamic router resolves
+ * one. `query()` and `mutation()` results fit with their inferred contexts.
+ */
+export type OperationChild<Query, Mutation> = RouterChild<Query, Mutation> & Pick<OperationDeclaration<"query" | "mutation">, "kind" | typeof NativeOperation>;
 /** Private key for a router's native definition. */
 export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */
@@ -64,7 +69,7 @@ export interface OperationOptions<Input, Output> {
 }
 /** Adapt metadata and approval without running user code. */
 export declare const operationOptions: <Input, Output>(options: OperationOptions<Input, Output>) => {
-    approval?: (context: Parameters<Approval<Input>>[0]) => Effect.Effect<"approved" | "denied" | "user-approval", unknown, never>;
+    approval?: (context: Parameters<Approval<Input>>[0]) => import("effect/Effect").Effect<"approved" | "denied" | "user-approval", unknown, never>;
     input: EffectSchema.Decoder<Input, never>;
     _meta?: {
         readonly [x: string]: EffectSchema.Json;
@@ -79,8 +84,18 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
     title?: string;
     description?: string;
 };
+/**
+ * Replace a native operation's approval. Property descriptors are copied so an output schema that
+ * a protocol adapter builds only when read stays lazy.
+ */
+export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
 export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+/**
+ * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
+ * reads them to choose an approval; the framework never infers one from them.
+ */
+export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
 export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
 /** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */

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

@@ -1,6 +1,6 @@
 /** One client's mounted queries and ordered optimistic write/read handoffs. */
 import { Effect } from "effect";
-import { Atom, AsyncResult } from "effect/unstable/reactivity";
+import { Atom, AsyncResult } from "effect/reactivity";
 import type { AppMutation } from "../contracts/optimistic.js";
 import type { OperationReference } from "../contracts/live.js";
 import { JsonValue } from "../contracts/schema.js";

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

@@ -0,0 +1,60 @@
+/**
+ * Authoring credential placements. A method's `request` callback runs once, when the provider is
+ * declared, with an opaque reference for each of the method's fields. It returns placements built
+ * from `header` or `query` and a value from `t`, `base64` and references; the result is stored
+ * as data. A reference is not a string: an untagged template literal fails when it is evaluated.
+ */
+import { Placement, type PlacementPart } from "../contracts/placement.js";
+import type { AccountRequest, FieldExposure } from "../contracts/provider.js";
+/** Throw when JavaScript turns a placement into a string, so untagged templates fail. */
+declare class NotAString {
+    #private;
+    constructor(described: string);
+    [Symbol.toPrimitive](): never;
+    toString(): never;
+    toJSON(): never;
+}
+/** A reference to one of the method's account fields, given to its `request` callback. */
+export declare class FieldRef<Name extends string = string> extends NotAString {
+    readonly field: Name;
+    constructor(field: Name);
+}
+/** A value template built with `t` or `base64`. */
+export declare class PlacementValue extends NotAString {
+    readonly parts: readonly PlacementPart[];
+    constructor(parts: readonly PlacementPart[]);
+}
+/** What a template may interpolate: literal text, a field reference or another value. */
+export type PlacementInput = string | FieldRef | PlacementValue;
+/** A value template: literal text with interpolated field references and values. */
+export declare const t: (strings: TemplateStringsArray, ...values: readonly PlacementInput[]) => PlacementValue;
+/** Base64 of a value's UTF-8 bytes, such as the `user:password` of Basic credentials. */
+export declare const base64: (value: PlacementInput) => PlacementValue;
+/** Send a value as the whole value of this header. The name is case-insensitive. */
+export declare const header: (name: string, input: PlacementInput) => Placement;
+/** Send a value as the whole value of this query parameter. */
+export declare const query: (name: string, input: unknown) => Placement;
+/** `Authorization: Bearer <token>`. */
+export declare const bearer: (token: FieldRef) => Placement;
+/** `Authorization: Basic base64(<user>:<password>)`. */
+export declare const basic: (user: PlacementInput, password: PlacementInput) => Placement;
+/** The field references a `request` callback receives, by field name. */
+export type FieldRefs<Name extends string> = {
+    readonly [Key in Name]: FieldRef<Key>;
+};
+/** How a method declares its placements: called once with its field references. */
+export type RequestPlacements<Name extends string> = (fields: FieldRefs<Name>) => Placement | readonly Placement[];
+/**
+ * Run a method's `request` callback once and check its placements. Every reference names one of
+ * the method's fields, no `raw()` field appears, and each placement references a secret field.
+ */
+export declare const declarePlacements: (method: string, names: readonly string[], exposure: Readonly<Record<string, FieldExposure>> | undefined, request: RequestPlacements<string>) => readonly Placement[];
+/**
+ * Give a bound account `headers()` and `url()`, rendering the placements the host granted with the
+ * fields app code holds. They are not enumerable, so the account's JSON is unchanged.
+ */
+export declare const withPlacements: <Account extends {
+    readonly method: string;
+    readonly fields: unknown;
+}>(account: Account, placements: readonly Placement[] | undefined) => Account & AccountRequest;
+export {};

package/types/apps/src/implementation/protocol-operations.d.ts

@@ -13,6 +13,9 @@ interface ProtocolOperation {
     readonly annotations?: ToolAnnotations | undefined;
     readonly _meta?: JsonObject | undefined;
     readonly input: Schema.Decoder<JsonValue>;
+    /** Checks and describes every returned value. */
+    readonly output?: Schema.Decoder<JsonValue> | undefined;
+    /** Describes the returned value without checking it; ignored when `output` is declared. */
     readonly outputSchema?: JsonObject | undefined;
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }

package/types/apps/src/implementation/provider-error.d.ts

@@ -1,10 +1,37 @@
 import { Option } from "effect";
+import type { FailurePhase, UpstreamError } from "../contracts/failure.js";
 import { ProviderError } from "../contracts/provider-error.js";
+import { AccountId } from "../contracts/schema.js";
+/** A provider failure's fields, each optional one possibly absent. */
+interface ProviderErrorFields {
+    readonly reason: ProviderError["reason"];
+    readonly status?: number | undefined;
+    readonly accountId?: AccountId | undefined;
+    readonly phase?: FailurePhase | undefined;
+    readonly upstream?: UpstreamError | undefined;
+}
+/**
+ * Construct a provider failure without keys for absent fields. Failures inside a catalog cross the
+ * boundary as JSON values, which have no `undefined`.
+ */
+export declare const providerError: ({ reason, status, accountId, phase, upstream, }: ProviderErrorFields) => ProviderError;
 /** Parse and rebuild the allowlisted fields, including when the input is already an Error instance. */
 export declare function parseProviderError(error: unknown): Option.Option<ProviderError>;
-/** Classify only explicit HTTP evidence. Raw provider content never enters the error. */
+/**
+ * The same failure with detail its raiser could not know: the phase it happened in, and the
+ * error the service stated. Detail the failure already carries is kept.
+ */
+export declare function providerErrorDetail(error: ProviderError, detail: {
+    readonly phase?: FailurePhase;
+    readonly upstream?: UpstreamError | undefined;
+}): ProviderError;
+/**
+ * Classify only explicit HTTP evidence. Raw provider content never enters the error; a Bearer
+ * challenge's documented error code and description do.
+ */
 export declare function httpProviderError(status: number, headers?: Readonly<Record<string, string>>): ProviderError | undefined;
 /** Attach the account used by the enclosing operation, without preserving arbitrary thrown fields. */
 export declare function accountProviderError<E>(error: E, accountId: string): E | ProviderError;
 /** GraphQL has no standard auth code; recognize these documented codes without guessing from prose. */
 export declare function graphqlProviderError(errors: readonly unknown[], status: number): ProviderError | undefined;
+export {};

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

@@ -1,21 +1,36 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
 import { type PromiseMethod } from "./authoring.js";
-import { type AccountCheck, type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import type { Placement } from "../contracts/placement.js";
 import type { ValidationError } from "../contracts/schema.js";
 /** Declare a secrets method with an Effect decoder. */
 export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options: {
     readonly label: string;
     readonly fields: Fields;
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
+    readonly request?: readonly Placement[];
 }) => SecretsMethod<Fields>;
 /** Validate OAuth endpoints while declaring their app-visible response projection. */
-export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>, request?: readonly Placement[]) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
 /** Author options: the account check is an ordinary async function. */
 export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
+    /**
+     * Hosts the credentials may be sent to: `api.example.com`, `api.example.com:8443`, or
+     * `*.example.com` for one level of subdomain. Secret fields then reach app code as handles
+     * that the outbound network replaces only on requests to these hosts. An account records the
+     * hosts it was connected for; changing them does not change the provider, but an existing
+     * account sends only to hosts it was connected for until it is connected again.
+     */
+    readonly hosts?: readonly string[];
     /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
     readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
 }
-/** Retain the provider and literal method names without registering or authenticating it. */
+/**
+ * Retain the provider and literal method names without registering or authenticating it. A
+ * method's `request` restricts where its credentials go only among the provider's `hosts`, so a
+ * provider that declares a `request` declares `hosts` too.
+ */
 export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;