apps 0.0.1-beta.5 → 0.0.1-beta.55

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

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

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

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

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "../contracts/provider-error.js";
+import type { NetworkRefused } from "../contracts/network.js";
 /** One upstream call, with form requests forwarded to the invocation's existing elicitation capability. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Effect, Schema } from "effect";
@@ -6,15 +7,15 @@ import { ElicitationFailed } from "../contracts/elicitation.js";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
 import type { JsonObject } from "../contracts/schema.js";
 /** Register prompts only around tools/call, preserve metadata, and close every callback with the call. Never retries. */
-export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError) => Effect.Effect<{
+export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError | NetworkRefused) => Effect.Effect<{
     readonly content: readonly {
         readonly [x: string]: Schema.Json;
     }[];
     readonly _meta?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
+    };
     readonly structuredContent?: {
         readonly [x: string]: Schema.Json;
-    } | undefined;
-    readonly isError?: boolean | undefined;
-}, ProviderError | ElicitationFailed | McpError, never>;
+    };
+    readonly isError?: boolean;
+}, ProviderError | NetworkRefused | ElicitationFailed | McpError, never>;

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

@@ -1,12 +1,11 @@
 import { Effect } from "effect";
-import type { DynamicTools } from "../contracts/dynamic-tools.js";
 import { McpToolsOptions } from "../contracts/mcp.js";
-import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type CatalogAccount, type CatalogCacheOptions } from "./catalog-cache.js";
 import { type OperationKinds } from "./protocol-operations.js";
-/** Metadata policy for HTTP/SSE sources. A missing cache keeps discovery invocation-local. */
-export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
-}
+/**
+ * A server, the account whose catalog it is, and the metadata policy for HTTP/SSE sources. A
+ * missing cache keeps discovery invocation-local.
+ */
+export type McpCatalogOptions = Omit<McpToolsOptions, "accountId" | "headers"> & CatalogCacheOptions & CatalogAccount;
 /** Construction opens no transport unless explicit revalidation is requested. */
-export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
-    dynamicTools: DynamicTools;
-}, unknown, never>;
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<import("./operations.js").RouterDeclaration<unknown, unknown>, unknown, never>;

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

@@ -1,51 +1,75 @@
 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<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly description?: string;
+            readonly version?: string;
+            readonly name?: string;
+            readonly instructions?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, 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,41 +1,68 @@
 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<{
-        readonly name: string;
-        readonly inputSchema: {
-            readonly [x: string]: Schema.Json;
-        };
-        readonly description?: string | undefined;
-        readonly _meta?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly title?: string | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-        readonly annotations?: {
+        tools: {
+            readonly name: string;
+            readonly inputSchema: {
+                readonly [x: string]: Schema.Json;
+            };
+            readonly description?: string | undefined;
+            readonly _meta?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+            readonly title?: string | undefined;
+            readonly annotations?: {
+                readonly title?: string;
+                readonly readOnlyHint?: boolean;
+                readonly destructiveHint?: boolean;
+                readonly idempotentHint?: boolean;
+                readonly openWorldHint?: boolean;
+            } | undefined;
+            readonly outputSchema?: {
+                readonly [x: string]: Schema.Json;
+            } | undefined;
+        }[];
+        server: {
+            readonly description?: string;
+            readonly version?: string;
+            readonly name?: string;
+            readonly instructions?: string;
             readonly title?: string;
-            readonly readOnlyHint?: boolean;
-            readonly destructiveHint?: boolean;
-            readonly idempotentHint?: boolean;
-            readonly openWorldHint?: boolean;
-        } | undefined;
-    }[], ProviderError | McpError, never>;
+            readonly icons?: readonly {
+                readonly src: string;
+                readonly mimeType?: string;
+                readonly sizes?: readonly string[];
+                readonly theme?: "light" | "dark";
+            }[];
+            readonly websiteUrl?: string;
+        } | {};
+    }, 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,34 @@
 /** 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 description: string;
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
-                readonly in: "query" | "path" | "header" | "cookie";
+                readonly in: "path" | "query" | "querystring" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -53,10 +63,12 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
                 readonly required?: boolean;
             };
         };
+        readonly path: string;
+        readonly name: string;
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -67,6 +79,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly outputSchema?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly tags?: readonly string[];
         readonly operationId?: string;
         readonly streaming?: true;
         readonly errorResponses?: readonly {
@@ -83,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,8 +3,8 @@ 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 { DynamicTools } from "../contracts/dynamic-tools.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. */
 export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operations" | "definitions"> {
     readonly cache: AppCache;
@@ -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;
     /**
@@ -33,8 +39,4 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
 /** JSON-object patches are static app configuration and are reapplied to every revision. */
 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 liveOpenapiOperations: (options: OpenapiSourceOptions) => {
-    readonly queries: {};
-    readonly mutations: {};
-    readonly dynamicTools: DynamicTools;
-};
+export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;

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