apps 0.0.1-beta.1 → 0.0.1-beta.100

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

@@ -0,0 +1,28 @@
+/** The icons an app declares beside its accounts, so a host shows them without evaluating it. */
+import { Schema } from "effect";
+/** At most this many icons, together at most this many characters of JSON (32 KiB). */
+export declare const appIconLimits: {
+    readonly icons: 8;
+    readonly characters: number;
+};
+/**
+ * One image an app shows for itself, the same shape as a router's icon. `theme` names the color
+ * scheme it is drawn for; an icon without one suits both.
+ */
+export declare const AppIcon: Schema.Struct<{
+    readonly src: Schema.String;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>;
+export type AppIcon = typeof AppIcon.Type;
+/** An app's icons, bounded in number and total size. */
+export declare const AppIcons: Schema.$Array<Schema.Struct<{
+    readonly src: Schema.String;
+    readonly mimeType: Schema.optionalKey<Schema.String>;
+    readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+}>>;
+export type AppIcons = typeof AppIcons.Type;
+/** Why declared icons are refused, in the author's terms, or undefined when they are valid. */
+export declare const appIconsProblem: (icons: unknown) => string | undefined;

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

@@ -1,6 +1,8 @@
 /** Browser subscription contracts contain no executable server declarations. */
 import { Schema } from "effect";
 import type { JsonValue } from "./schema.js";
+/** Names of authored operations. */
+export declare const OperationName: Schema.NonEmptyString;
 /** Serializable named reference; the phantom field is never populated at runtime. */
 export interface OperationReference<Input, Output, Kind extends "query" | "mutation"> {
     readonly name: string;

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

@@ -1,7 +1,9 @@
-import type { ProviderError } from "./provider-error.js";
+import { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** MCP protocol data uses Effect Schema; executable tool methods use Effect. */
 import { type Effect, type Redacted, Schema } from "effect";
 import type { Elicit, ElicitationFailed } from "./elicitation.js";
+import type { AccountCheckContext, AuthMethods } from "./provider.js";
 import { type JsonValue } from "./schema.js";
 /** Upstream MCP resource bounds, independent of the outer codemode execution budget. */
 export declare const McpClientLimits: Schema.Struct<{
@@ -12,7 +14,7 @@ export declare const McpClientLimits: Schema.Struct<{
     readonly cleanupTimeoutMs: Schema.Int;
 }>;
 export type McpClientLimits = typeof McpClientLimits.Type;
-/** HTTP and stdio share discovery ceilings and the default provider timeout. */
+/** Discovery ceilings and the default provider timeout. */
 export declare const defaultMcpClientLimits: {
     readonly timeoutMs: number;
     readonly maxTimeoutMs: number;
@@ -31,6 +33,37 @@ export declare const McpToolsOptions: Schema.Struct<{
     readonly timeoutMs: Schema.optional<Schema.Number>;
 }>;
 export type McpToolsOptions = typeof McpToolsOptions.Type;
+/**
+ * What `mcpHealth` checks, as decoded: its options, with the account's ID, signal and deadline
+ * taken from the check context.
+ */
+export declare const McpHealthInput: Schema.Struct<{
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly deadline: Schema.optional<Schema.Finite>;
+    readonly url: Schema.String;
+    readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
+    readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>;
+/**
+ * The server a provider check verifies, and the headers that send the checked account's
+ * credentials. The account, signal and deadline come from the check context instead. Both attempts
+ * share one budget that ends `mcpHealthReserveMs` before the deadline. `timeoutMs` bounds the whole
+ * check too; it can shorten the budget, never extend it.
+ */
+export type McpHealthOptions = Pick<typeof McpHealthInput.Type, "url" | "headers" | "timeoutMs">;
+/** What `mcpHealth` reads from the check context the host passes to a provider's `health`. */
+export type McpHealthCheck = Pick<AccountCheckContext<AuthMethods>, "signal" | "deadline"> & {
+    readonly account: {
+        readonly id: string;
+    };
+};
+/**
+ * How long before an account check's deadline `mcpHealth` stops waiting for the server, so it can
+ * still close its session, ending it and then its transport, each within `cleanupTimeoutMs`, and
+ * report why before the host stops waiting.
+ */
+export declare const mcpHealthReserveMs: number;
 /** One parsed server and credential snapshot; never shared across account evaluations. */
 export interface McpConnection {
     readonly url: URL;
@@ -38,15 +71,21 @@ export interface McpConnection {
     readonly timeoutMs: number;
 }
 export { ToolAnnotations as McpToolAnnotations } from "./tools.js";
-/** Native MCP result semantics. Protocol/transport failures use the Effect error channel. */
+/**
+ * Native MCP result semantics, and the value every MCP tool call returns. A tool's output
+ * schema is built from this declaration. Protocol/transport failures use the Effect error channel.
+ */
 export declare const McpToolResult: Schema.Struct<{
     readonly content: Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly structuredContent: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly isError: Schema.optional<Schema.Boolean>;
-    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly structuredContent: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly isError: Schema.optionalKey<Schema.Boolean>;
+    readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolResult = typeof McpToolResult.Type;
-/** Remote metadata. Input/output schemas remain upstream JSON Schema documents. */
+/**
+ * Remote metadata. Input/output schemas remain upstream JSON Schema documents; the upstream
+ * output schema describes only a result's `structuredContent`.
+ */
 export declare const McpToolMetadata: Schema.Struct<{
     readonly name: Schema.String;
     readonly title: Schema.optional<Schema.String>;
@@ -63,16 +102,37 @@ export declare const McpToolMetadata: Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolMetadata = typeof McpToolMetadata.Type;
+/** What a server reports about itself when a session initializes. Icons are for display only. */
+export declare const McpServerHeader: Schema.Struct<{
+    readonly name: Schema.optionalKey<Schema.String>;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly websiteUrl: Schema.optionalKey<Schema.String>;
+    readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly src: Schema.NonEmptyString;
+        readonly mimeType: Schema.optionalKey<Schema.String>;
+        readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+    }>>>;
+    readonly instructions: Schema.optionalKey<Schema.String>;
+}>;
+export type McpServerHeader = typeof McpServerHeader.Type;
 /** Direct callers can omit interaction capabilities. A server that asks for input then fails explicitly. */
 export interface McpToolContext {
     readonly elicit?: Elicit;
 }
-/** A tool bound to one evaluation's account; do not reuse it with another account. */
-export interface McpTool extends McpToolMetadata {
+/**
+ * A tool bound to one evaluation's account; do not reuse it with another account. `output`
+ * decodes and describes the `McpToolResult` that `run` returns, with the upstream output schema
+ * under `structuredContent`.
+ */
+export interface McpTool extends Omit<McpToolMetadata, "outputSchema"> {
     readonly description: string;
     readonly input: Schema.Decoder<JsonValue>;
+    readonly output: Schema.Decoder<JsonValue>;
     readonly readOnly?: boolean;
-    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | ElicitationFailed>;
+    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | NetworkRefused | ElicitationFailed>;
 }
 /** The discovered catalog keyed by remote tool name. */
 export type McpTools = Readonly<Record<string, McpTool>>;
@@ -80,16 +140,33 @@ declare const McpError_base: Schema.Class<McpError, Schema.TaggedStruct<"McpErro
     readonly phase: Schema.Literals<readonly ["connect", "discover", "call", "schema", "transport"]>;
     readonly reason: Schema.Literals<readonly ["request", "unauthorized", "invalid_response", "timeout", "invalid_input"]>;
     readonly status: Schema.optional<Schema.Number>;
+    readonly upstream: Schema.optional<Schema.Struct<{
+        readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+        readonly message: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly session: Schema.optional<Schema.Literal<true>>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe protocol/transport failure; no raw upstream payloads or credentials. */
+/**
+ * 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`. `session` is set when the refused
+ * request carried the session ID the server issued at initialization.
+ *
+ * These fields describe the failure for whoever reads it. App code can set any of them, so they
+ * never show that the failure lies outside Executor.
+ */
 export declare class McpError extends McpError_base {
 }
-/** Public process configuration. Credentials arrive through the selected account. */
-export declare const ProcessConfig: Schema.Struct<{
-    readonly command: Schema.NonEmptyString;
-    readonly args: Schema.$Array<Schema.String>;
-    readonly cwd: Schema.optional<Schema.String>;
-    readonly env: Schema.$Record<Schema.String, Schema.String>;
-    readonly timeoutMs: Schema.Int;
-}>;
-export type ProcessConfig = typeof ProcessConfig.Type;
+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 {
+}

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

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

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

@@ -1,11 +1,90 @@
 /** 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"]>;
+/** Which part of an OpenAPI document could not be compiled into tools. */
+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;
 }
+/** A tool a generated OpenAPI router exposes, read from the definition alone. */
+export declare const OpenapiToolName: Schema.Struct<{
+    /** The tool name relative to the router, as `withApprovals` receives it. */
+    readonly name: Schema.String;
+    /** The HTTP method, such as `GET`. */
+    readonly method: Schema.String;
+    /** The request path, including any `pathPrefix`. */
+    readonly path: Schema.String;
+    readonly operationId: Schema.optionalKey<Schema.String>;
+    /** After `kinds` (keyed by `operationId`, else `name`); otherwise reading methods are queries. */
+    readonly kind: Schema.Literals<readonly ["query", "mutation"]>;
+    /** Callable without credentials, so every account and a router without one expose it. */
+    readonly public: Schema.Boolean;
+    /** The `methods` and `oauth` entries whose accounts expose it. */
+    readonly methods: Schema.$Array<Schema.String>;
+}>;
+export type OpenapiToolName = typeof OpenapiToolName.Type;
+/** Every tool a definition yields for some account, and the operations the compiler left out. */
+export declare const OpenapiToolNames: Schema.Struct<{
+    readonly tools: Schema.$Array<Schema.Struct<{
+        /** The tool name relative to the router, as `withApprovals` receives it. */
+        readonly name: Schema.String;
+        /** The HTTP method, such as `GET`. */
+        readonly method: Schema.String;
+        /** The request path, including any `pathPrefix`. */
+        readonly path: Schema.String;
+        readonly operationId: Schema.optionalKey<Schema.String>;
+        /** After `kinds` (keyed by `operationId`, else `name`); otherwise reading methods are queries. */
+        readonly kind: Schema.Literals<readonly ["query", "mutation"]>;
+        /** Callable without credentials, so every account and a router without one expose it. */
+        readonly public: Schema.Boolean;
+        /** The `methods` and `oauth` entries whose accounts expose it. */
+        readonly methods: Schema.$Array<Schema.String>;
+    }>>;
+    /**
+     * Operations the compiler left out, and why. An operation it imports but no configured `methods`
+     * or `oauth` entry can authorize is missing from `tools` and is not listed here.
+     */
+    readonly skipped: 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;
+    }>>;
+}>;
+export type OpenapiToolNames = typeof OpenapiToolNames.Type;
 export {};

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

@@ -1,4 +1,4 @@
-/** OpenAPI boundary parsing. Unsupported transport/auth features fail before deployment. */
+/** OpenAPI boundary parsing. Unsupported transport/auth features fail before deploying. */
 import { Schema } from "effect";
 /** Parsed OpenAPI 3 source; individual operation references are resolved separately. */
 export declare const Specification: Schema.Struct<{

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** Credential-free OpenAPI request declarations and validation schemas retained with app source. */
 import { Schema, type Effect } from "effect";
 import { JsonObject } from "./schema.js";
@@ -20,7 +21,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>;
@@ -40,9 +42,12 @@ export declare const OpenapiRequestBody: Schema.Struct<{
 }>;
 /** Credential-free operation data emitted by the OpenAPI importer. */
 export declare const OpenapiOperation: Schema.Struct<{
+    /** The tool name after `queries.` or `mutations.`, grouped as `<group>.<leaf>`. */
     readonly name: Schema.NonEmptyString;
+    /** 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;
@@ -51,7 +56,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>;
@@ -72,6 +78,8 @@ export declare const OpenapiOperation: Schema.Struct<{
     }>;
     /** Streams remain in the metadata but cannot run through a single-result tool call. */
     readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+    /** The operation's OpenAPI tags, shown to agents as labels within its router. */
+    readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
     readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
@@ -87,6 +95,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 "HEAD" | "GET" | "OPTIONS" | "QUERY";
 /** Map a selected account field to one Swagger credential value. */
 export declare const CredentialBinding: Schema.Struct<{
     readonly scheme: Schema.String;
@@ -115,9 +125,12 @@ export type OpenapiParameterDefaults = typeof OpenapiParameterDefaults.Type;
 /** Parsed options for one account's evaluation. */
 export declare const OpenapiToolsOptions: Schema.Struct<{
     readonly operations: Schema.$Array<Schema.Struct<{
+        /** The tool name after `queries.` or `mutations.`, grouped as `<group>.<leaf>`. */
         readonly name: Schema.NonEmptyString;
+        /** 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;
@@ -126,7 +139,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>;
@@ -147,6 +161,8 @@ export declare const OpenapiToolsOptions: Schema.Struct<{
         }>;
         /** Streams remain in the metadata but cannot run through a single-result tool call. */
         readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+        /** The operation's OpenAPI tags, shown to agents as labels within its router. */
+        readonly tags: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
         readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
         readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
         readonly errorResponses: Schema.optionalKey<Schema.$Array<Schema.Struct<{
@@ -191,11 +207,32 @@ export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operati
     readonly operations: unknown;
     readonly definitions?: unknown;
 };
+/** The operation a failed call addressed: its method and templated path, never parameter values. */
+export declare const OpenapiFailedOperation: Schema.Struct<{
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
+    readonly path: Schema.String;
+}>;
+export type OpenapiFailedOperation = typeof OpenapiFailedOperation.Type;
+/** A response media type without parameters, such as `text/html`. */
+export declare const OpenapiMediaType: Schema.String;
 declare const OpenapiError_base: Schema.Class<OpenapiError, Schema.TaggedStruct<"OpenapiError", {
     readonly reason: Schema.Literals<readonly ["invalid_definition", "invalid_input", "request"]>;
     readonly status: Schema.optional<Schema.Number>;
+    /** Absent only when the definition itself could not be read. */
+    readonly operation: Schema.optional<Schema.Struct<{
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"]>;
+        readonly path: Schema.String;
+    }>>;
+    readonly contentType: Schema.optional<Schema.String>;
+    /** The response's `content-length`, when it declared one. */
+    readonly bytes: Schema.optional<Schema.Int>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe failures omit request headers, credentials and upstream bodies. */
+/**
+ * Safe failures omit request headers, credentials and upstream body text: the failure message is
+ * also recorded in traces. A `request` failure with a status names the response that no declared
+ * error matched, or the success response whose body could not be read, by its media type and
+ * declared length.
+ */
 export declare class OpenapiError extends OpenapiError_base {
 }
 /** An ordinary native tool bound to one selected account. */
@@ -204,7 +241,7 @@ export interface OpenapiTool {
     readonly readOnly: boolean;
     readonly outputSchema?: JsonObject;
     readonly input: Schema.Decoder<Schema.Json>;
-    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError | OpenapiResponseError | ProviderError | NetworkRefused>;
 }
 /** Executable operations keyed by their generated names. */
 export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;
@@ -213,7 +250,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. */
@@ -221,5 +263,5 @@ export declare const isOpenapiFileSchema: (shape: Readonly<Record<string, unknow
 /** JSON-safe binary result, independent of the host's file storage. */
 export declare const openapiBinaryResultSchema: JsonObject;
 /** Classify request media for JSON-safe tool arguments; Swagger owns wire serialization. */
-export declare const openapiMediaKind: (type: string) => "form" | "text" | "binary" | "json" | "multipart";
+export declare const openapiMediaKind: (type: string) => "form" | "json" | "binary" | "multipart" | "text";
 export {};

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

@@ -1,13 +1,16 @@
-/** Native operation declarations. Database access is an optional invocation capability. */
+/** Native operation declarations. SQL access is an optional invocation capability. */
 import type { Effect, Schema } from "effect";
 import type { Approval } from "./approval.js";
-import type { BoundContext, AccountSlots } from "./app.js";
-import type { Database, DatabaseReader, Tables } from "./storage.js";
+import type { EvaluationContext, ScopedSlots } from "./app.js";
+import type { Sql, SqlReader } from "./sql.js";
 import type { ToolAnnotations } from "./tools.js";
 import type { JsonObject } from "./schema.js";
-/** Host-bound operation capabilities; the author declaration refines accounts and storage. */
-export type OperationContext = BoundContext<AccountSlots> & {
-    readonly db?: DatabaseReader<Tables> | Database<Tables>;
+/**
+ * Host-bound operation capabilities; the author declaration refines accounts and storage. `user` is
+ * absent when the invocation has no caller.
+ */
+export type OperationContext = EvaluationContext<ScopedSlots> & {
+    readonly sql?: SqlReader | Sql;
 };
 /** The host validates input, checks approval, then owns the transaction and output validation. */
 export interface AppOperation<Input = unknown, Output = unknown> {
@@ -17,14 +20,13 @@ export interface AppOperation<Input = unknown, Output = unknown> {
     readonly annotations?: ToolAnnotations;
     readonly _meta?: JsonObject;
     readonly input: Schema.Decoder<Input>;
+    /** Checks every value `run` returns and is the output schema the operation is described with. */
     readonly output?: Schema.Decoder<Output>;
-    /** Upstream protocol result metadata; the protocol adapter validates its own result envelope. */
+    /**
+     * An upstream protocol's description of the value `run` returns, used only when `output` is
+     * absent. The host does not check it, so declare `output` when the result can be checked.
+     */
     readonly outputSchema?: JsonObject;
     readonly approval?: Approval<Input>;
     readonly run: (context: OperationContext, input: Input) => Effect.Effect<Output, unknown>;
 }
-/** Agent tool names carry the operation kind; catalogs may reuse the same local name. */
-export declare const OperationToolPrefixes: {
-    readonly query: "queries.";
-    readonly mutate: "mutations.";
-};