apps 0.0.1-beta.23 → 0.0.1-beta.25

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/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/ui-client.d.ts

@@ -1,4 +1,4 @@
-import { Atom } from "effect/unstable/reactivity";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
 import { type OperationReference } from "../contracts/live.js";
 import { type Schema } from "./schema.js";
 /** A scoped page client. Host-injected context carries only the deployment, never credentials. */
@@ -12,5 +12,5 @@ export declare const createAppClient: () => {
     /** Create a callable mutation with optional withOptimisticUpdate projections over mounted queries. */
     mutation: <Input, Output>(reference: OperationReference<Input, Output, "mutation">, output: Schema<NoInfer<Output>, boolean>) => import("../client.js").AppMutation<Input, Output>;
     /** Share a live query across mounts and reconcile optimistic changes against fresh server reads. */
-    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<import("effect/unstable/reactivity/AsyncResult").AsyncResult<Output, unknown>>;
+    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<AsyncResult.AsyncResult<Output, unknown>>;
 };

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