apps 0.0.1-beta.24 → 0.0.1-beta.26

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

@@ -3,12 +3,21 @@ declare const ProviderError_base: Schema.Class<ProviderError, Schema.TaggedStruc
     readonly reason: Schema.Literals<readonly ["unauthorized", "forbidden", "rate_limited", "unavailable", "rejected"]>;
     readonly status: Schema.optional<Schema.Int>;
     readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
+    readonly phase: Schema.optional<Schema.Literals<readonly ["connect", "discover", "call"]>>;
+    readonly upstream: Schema.optional<Schema.Struct<{
+        readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+        readonly message: Schema.optionalKey<Schema.String>;
+    }>>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A recognized service failure. App authors can throw this ordinary Error from
  * async code. Supply only a known reason and the account used for that request.
  * Never include response bodies, messages, URLs or credentials. A bare 403 is
  * `rejected`; `forbidden` requires explicit evidence of insufficient permission.
+ *
+ * The framework adds the phase the failure happened in, and `upstream`: the error code and
+ * description the service stated in its documented error format, such as a Bearer challenge's
+ * `error` and `error_description`. Account secrets in that text are replaced.
  */
 export declare class ProviderError extends ProviderError_base {
 }

package/types/apps/src/implementation/failure-detail.d.ts

@@ -1,11 +1,15 @@
-import { Redacted } from "effect";
+import { Option, Redacted } from "effect";
 import type { ResolvedAccounts } from "../contracts/host.js";
+import { McpError } from "../contracts/mcp.js";
+import type { ProviderError } from "../contracts/provider-error.js";
+import { type FailureFields, type FailurePhase, type UpstreamError } from "../contracts/failure.js";
 /** Fields of `FailureDetail` as constructor input. */
 export interface FailureDetail {
     readonly source?: "app" | "storage" | "service";
     readonly errorName?: string;
     readonly code?: string;
     readonly message?: string;
+    readonly fields?: FailureFields;
 }
 /**
  * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
@@ -16,11 +20,26 @@ export declare const accountFieldSecrets: (accounts: unknown) => string[];
 export declare const accountSecrets: (accounts: Redacted.Redacted<ResolvedAccounts>) => string[];
 /** Replace account secrets and bound the message for the runtime boundary. */
 export declare const boundFailureMessage: (message: string, secrets: readonly string[]) => string;
+/**
+ * Replace account secrets in the error a service stated, as it leaves the bundle. A message
+ * shortened where it was read can end partway through a secret; that part is replaced too.
+ */
+export declare const redactUpstream: (upstream: UpstreamError | undefined, secrets: readonly string[]) => UpstreamError | undefined;
+/**
+ * A provider failure as it leaves the bundle: in the phase it happened, unless its raiser named a
+ * more precise one, with account secrets replaced in the error the service stated.
+ */
+export declare const leavingProviderError: (error: ProviderError, secrets: readonly string[], phase?: FailurePhase) => ProviderError;
+/**
+ * Rebuild an MCP failure's allowlisted fields, with account secrets replaced in the server's
+ * error. Absent fields have no key, as catalogs cross the boundary as JSON values.
+ */
+export declare const parseMcpError: (error: unknown, secrets: readonly string[]) => Option.Option<McpError>;
 /** `Name: message` for any thrown value, before redaction. */
 export declare const describeFailure: (error: unknown) => string;
 /**
  * Describe what an operation raised for the app's own caller. App data failures keep their
- * reason as a code, as do app cache failures; any other thrown value is the app's own error.
- * Account secrets are replaced.
+ * reason as a code, as do app cache failures; any other thrown value is the app's own error, with
+ * its own code and scalar fields. Account secrets are replaced.
  */
 export declare const failureDetail: (error: unknown, secrets: readonly string[]) => FailureDetail;

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

@@ -4,7 +4,13 @@ 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. */

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

@@ -11,6 +11,8 @@ import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/ope
 export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
     readonly allowedOrigin?: string;
+    /** Inserted between every operation's server and path; see `prefixParameters`. */
+    readonly pathPrefix?: string;
     readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
@@ -19,7 +21,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly request: {
             readonly parameters: readonly {
                 readonly name: string;
-                readonly in: "query" | "path" | "header" | "cookie";
+                readonly in: "query" | "path" | "querystring" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -59,7 +61,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -87,6 +89,14 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         }[];
     }[];
+    /** Declared operations left out of `operations`, in definition order. */
+    skipped: {
+        readonly name: string;
+        readonly method: string;
+        readonly path: string;
+        readonly code: "server_protocol" | "server_url" | "external_reference" | "circular_reference" | "schema_keyword" | "schema_reference" | "missing_component" | "openapi_version" | "auth_helper" | "auth_missing" | "operation_path" | "operation_method" | "duplicate_operation" | "server_missing" | "multiple_hosts" | "parameter_encoding" | "parameter_style" | "request_body" | "combined_oauth" | "auth_method" | "event_stream" | "input_schema" | "no_operations" | "no_supported_operations" | "invalid_document" | "source_generation" | "authoring_reference";
+        readonly reason: string;
+    }[];
     definitions: {
         [k: string]: {
             readonly [x: string]: Schema.Json;

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

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

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

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

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

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

package/types/apps/src/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/router-catalog.d.ts

@@ -4,7 +4,6 @@
  */
 import { Effect, Schema } from "effect";
 import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
-import { McpError } from "../contracts/mcp.js";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
 import { SkillLoadFailed } from "../contracts/skills.js";
@@ -189,7 +188,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
     })[];
     routers: {
         readonly path: string;
-        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed;
+        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError;
         readonly description?: string;
         readonly title?: string;
         readonly tags?: {
@@ -203,7 +202,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
         }[];
         readonly skill?: string;
     }[];
-}, import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed, never>;
+}, import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError, never>;
 /**
  * One skill for each router with instructions. Skills and tools fail independently: a dynamic
  * router whose metadata cannot be read, including the root, contributes no skill and does not

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

@@ -0,0 +1,7 @@
+import { UpstreamError } from "../contracts/failure.js";
+/** Whether `bounded` shortened this message, so it may end partway through a secret. */
+export declare const isShortenedUpstream: (message: string) => boolean;
+/** The error a JSON error body states, if it uses JSON-RPC's or OAuth's error format. */
+export declare const bodyUpstreamError: (json: unknown) => UpstreamError | undefined;
+/** The `error` and `error_description` of a Bearer challenge (RFC 6750, section 3). */
+export declare const challengeUpstreamError: (header: string | undefined) => UpstreamError | undefined;

package/types/telemetry/src/config.d.ts

@@ -33,8 +33,8 @@ export declare const TelemetryConfig: Schema.Struct<{
 export type TelemetryConfig = typeof TelemetryConfig.Type;
 /** Host-only destinations; never copied into an app's invocation telemetry capability. */
 export declare const CurrentTelemetryConfig: Context.Reference<{
-    readonly version: string;
     readonly service: string;
+    readonly version: string;
     readonly environment: string;
     readonly clock?: "system" | "cloudflare-io" | undefined;
     readonly traces?: {
@@ -59,8 +59,8 @@ export declare const CurrentTelemetryConfig: Context.Reference<{
 } | undefined>;
 /** Read OTLP endpoints uniformly for all signals; development chooses which signals to configure. */
 export declare const telemetryConfig: (service: string) => Effect.Effect<{
-    readonly version: string;
     readonly service: string;
+    readonly version: string;
     readonly environment: string;
     readonly clock?: "system" | "cloudflare-io" | undefined;
     readonly traces?: {

package/js/chunk-MKWZPDR6.js

@@ -1,63 +0,0 @@
-import {
-  ProviderError
-} from "./chunk-R3EV5FTO.js";
-import {
-  AccountId
-} from "./chunk-27F7W2LG.js";
-import {
-  Option_exports,
-  Schema_exports
-} from "./chunk-CDL5PM2Q.js";
-
-// src/implementation/provider-error.ts
-function parseProviderError(error) {
-  return Schema_exports.decodeUnknownOption(ProviderError)(error).pipe(
-    Option_exports.map(({ reason, status, accountId }) => new ProviderError({ reason, status, accountId }))
-  );
-}
-function httpProviderError(status, headers = {}) {
-  if (status >= 500 && status <= 599) return new ProviderError({ reason: "unavailable", status });
-  if (status === 401) return new ProviderError({ reason: "unauthorized", status });
-  if (status === 429) return new ProviderError({ reason: "rate_limited", status });
-  if (status !== 403) return void 0;
-  const retry = headers["retry-after"];
-  if (headers["x-ratelimit-remaining"] === "0" || retry !== void 0 && (/^\d+$/.test(retry) || Number.isFinite(Date.parse(retry))))
-    return new ProviderError({ reason: "rate_limited", status });
-  if (/\bBearer\b.*\berror="insufficient_scope"/i.test(headers["www-authenticate"] ?? ""))
-    return new ProviderError({ reason: "forbidden", status });
-  return new ProviderError({ reason: "rejected", status });
-}
-function accountProviderError(error, accountId) {
-  const parsed = parseProviderError(error);
-  const account = Schema_exports.decodeUnknownOption(AccountId)(accountId);
-  if (Option_exports.isNone(parsed) || Option_exports.isNone(account)) return error;
-  return new ProviderError({
-    reason: parsed.value.reason,
-    status: parsed.value.status,
-    accountId: account.value
-  });
-}
-function graphqlProviderError(errors, status) {
-  const codes = errors.flatMap((error) => {
-    const parsed = Schema_exports.decodeUnknownOption(
-      Schema_exports.Struct({
-        type: Schema_exports.optional(Schema_exports.String),
-        extensions: Schema_exports.optional(Schema_exports.Struct({ code: Schema_exports.optional(Schema_exports.String) }))
-      })
-    )(error);
-    return Option_exports.isSome(parsed) ? [parsed.value.type, parsed.value.extensions?.code] : [];
-  });
-  if (codes.includes("RATE_LIMITED") || codes.includes("TOO_MANY_REQUESTS"))
-    return new ProviderError({ reason: "rate_limited", status });
-  if (codes.includes("UNAUTHENTICATED"))
-    return new ProviderError({ reason: "unauthorized", status });
-  if (codes.includes("FORBIDDEN")) return new ProviderError({ reason: "forbidden", status });
-  return void 0;
-}
-
-export {
-  parseProviderError,
-  httpProviderError,
-  accountProviderError,
-  graphqlProviderError
-};