apps 0.0.1-beta.42 → 0.0.1-beta.44

package/types/telemetry/src/browser-operations.d.ts

@@ -8,7 +8,7 @@ import { HttpClient, HttpClientError } from "effect/http";
 export declare const browserPageId: () => string | undefined;
 /** Safe event shared with the host's error reporter and product analytics. */
 export declare const BrowserOperationFailure: Schema.Struct<{
-    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
+    readonly error_type: Schema.Literals<readonly ["BrowserDecodeFailed", "BrowserConnectionFailed", "BrowserTransportFailed", "BrowserOperationFailed"]>;
     readonly trace_id: Schema.String;
     readonly span_id: Schema.String;
     readonly page_id: Schema.String;

package/types/telemetry/src/recorded-failure.d.ts

@@ -1,20 +1,29 @@
 /**
- * Failures as Executor's telemetry records them. An error whose message can carry an app's own
- * text declares a fixed sentence instead (see `RecordedMessage`); traces and error reports record
- * that sentence with the error's name. The error itself, and what its caller receives, are
- * unchanged.
+ * Failures as Executor's telemetry records them. Traces and error reports keep an error's text only
+ * when Executor wrote it: a tagged error is recorded by its tag and the fixed sentence it declares
+ * (see `RecordedMessage`), or by its tag alone when it declares none. Its fields, message, stack and
+ * cause are not recorded, so a value an error carries for its caller, an app's text or a service's
+ * reply cannot reach telemetry by an error forgetting to declare. The error itself, and what its
+ * caller receives, are unchanged.
  */
 import { Cause } from "effect";
 /**
- * The error a trace or error report records in place of `error`. Its stack is generated here and
- * names no frames: the error's own stack begins with its message, which can span lines that look
- * like frames, so none of its text is kept. Traces still show where it failed through the
- * operation's own spans, which Effect appends to a recorded stack.
+ * The error a trace or error report records in place of `error`.
+ *
+ * - A tagged error is named by its tag: a field called `name`, such as a requested skill's or an
+ *   app's, replaces the error's own name. Its message is the sentence it declares, or empty. Its
+ *   stack is generated here and names no frames: the error's own stack begins with its message,
+ *   which can span lines that look like frames. Traces still show where it failed through the
+ *   operation's own spans, which Effect appends to a recorded stack.
+ * - Any other value that is not an `Error`, such as a plain object Effect would print as JSON, is
+ *   recorded as `UnrecognizedFailure` with no text.
+ * - An untagged `Error` is a defect or a platform's error: its message and stack come from the
+ *   JavaScript engine or a library and are kept, as they are the only diagnosis of an Executor bug.
+ *   Its cause is recorded by these same rules.
  */
 export declare const recordedError: (error: unknown) => unknown;
 /**
- * A failure's cause as traces record it. A defect is recorded the same way when it is an error that
- * declares a recorded message, such as a workflow failure a host turned into a defect; other
- * defects and interruptions are unchanged. Each reason keeps its annotations, which locate it.
+ * A failure's cause as traces record it: each failure and defect by `recordedError`. Interruptions
+ * are unchanged, and each reason keeps its annotations, which locate it.
  */
 export declare const recordedCause: <E>(cause: Cause.Cause<E>) => Cause.Cause<unknown>;

package/types/utils/src/api-error.d.ts

@@ -24,8 +24,10 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
      */
     readonly message: string | ((fields: Schema.Struct.Type<Fields>) => string);
     /**
-     * What traces and error reports record instead of `message`, when the message quotes an app's
-     * own error or a service's stated error for its caller. Only fixed text and typed fields.
+     * What traces and error reports record beside the tag. A fixed `message` is recorded as is; a
+     * message derived from fields is recorded only through this, from fixed text and closed fields,
+     * never a value the caller chose, an app's text or a service's reply. Without it the error is
+     * recorded by its tag alone.
      */
     readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
 };

package/types/utils/src/connection-failure.d.ts

@@ -0,0 +1,33 @@
+/** Requests the browser could not complete because no response reached it. */
+import { Cause } from "effect";
+import { HttpClientError } from "effect/http";
+import { UserFacingError } from "./user-facing-error.js";
+/**
+ * Fetch rejects with a `TypeError` when no response arrives: the device is offline, the page
+ * navigated away first, the connection was reset before a response, or the browser blocked the
+ * request. The server may still have completed the request and records its own outcome. Failures Executor constructs itself, such as a batch reply
+ * that ended without an answer, carry no such cause and stay unexpected.
+ */
+export declare const isConnectionFailure: (error: unknown) => error is HttpClientError.HttpClientError;
+/** Typed API clients may surface a lost connection as a failure or, after narrowing, a defect. */
+export declare const hasConnectionFailure: (cause: Cause.Cause<unknown>) => boolean;
+/** The browser could not reach Executor. Nothing on the server needs fixing. */
+export declare const ConnectionFailed: import("effect/Schema").Class<{} & UserFacingError & {
+    readonly _tag: "ConnectionFailed";
+}, Omit<import("effect/Schema").TaggedStruct<"ConnectionFailed", {
+    readonly message: typeof import("./api-error.js").MessageField;
+    readonly recovery: import("effect/Schema").decodeTo<import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>>, import("effect/Schema").Struct<{
+        readonly action: import("effect/Schema").String;
+        readonly instructions: import("effect/Schema").String;
+    }>, never, never>;
+}>, "~type.make.in"> & {
+    readonly "~type.make.in": {
+        readonly _tag?: "ConnectionFailed";
+    };
+}, UserFacingError>;
+export type ConnectionFailed = typeof ConnectionFailed.Type;
+/** What to show for a failure no contract declares: a lost connection, or an unexpected error. */
+export declare const undeclaredError: (cause: Cause.Cause<unknown>) => UserFacingError;

package/types/utils/src/recorded-message.d.ts

@@ -1,8 +1,11 @@
 /**
- * What traces and error reports record for an error in place of its message. An error declares
- * one when its message can carry text from outside Executor: an app's own error or output, or an
- * error a service stated through an app. That text still reaches the caller the error is for;
- * Executor's telemetry records only this fixed sentence, beside the error's name.
+ * The fixed sentence traces and error reports record for a tagged error, beside its tag. Telemetry
+ * records no other text from a tagged error: one that declares no sentence is recorded by its tag
+ * alone (`@executor-js/telemetry/recorded-failure`). Declare one from fixed text and closed fields
+ * only, never from a value the caller supplied (a slug, a name, a tool name, an argument's key),
+ * an app's own text or a service's reply. That text still reaches the caller the error is for.
+ * `ApiError` and `UserFacingError` declare a fixed message for you; a message derived from fields
+ * declares `recorded`.
  */
 export declare const RecordedMessage: unique symbol;
 /** The fixed sentence an error declares for telemetry, if it declares one. */

package/types/utils/src/user-facing-error.d.ts

@@ -0,0 +1,83 @@
+import { Schema, type Cause } from "effect";
+import "effect/http-api";
+import { MessageField } from "./api-error.js";
+/** Curated explanation and recovery. Never include raw diagnostics, credentials, or form values. */
+export interface ErrorPresentation {
+    readonly title: string;
+    readonly description: string;
+    readonly recovery: {
+        readonly action: string;
+        readonly instructions: string;
+    };
+    /** Repeating the failed operation can help. Configuration changes are not retries. */
+    readonly retryable?: boolean;
+    /** False when the user's agent cannot act on the fix prompt, so hosts do not offer it. */
+    readonly agentFixable?: boolean;
+    /** One safe value the user needs for recovery, such as a URL to send to the service. */
+    readonly detail?: {
+        readonly label: string;
+        readonly value: string;
+    };
+    /**
+     * Present only when the Executor team must fix the problem. Safe evidence for a public
+     * report: fixed codes and statuses, never user data, URLs, or upstream text.
+     */
+    readonly report?: string;
+}
+type PresentationProperties = Required<Omit<ErrorPresentation, "detail" | "report">> & {
+    readonly detail: ErrorPresentation["detail"];
+    readonly report: ErrorPresentation["report"];
+    readonly code: string;
+    readonly fixPrompt: string;
+};
+/** A yieldable error that owns its safe user explanation and agent recovery task. */
+export interface UserFacingError extends Cause.YieldableError, PresentationProperties {
+    readonly _tag: string;
+}
+type Header<Tag extends string> = {
+    readonly tag: Tag;
+    readonly status: number;
+};
+type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Header<Tag> & {
+    readonly fields: Fields & {
+        readonly [Key in keyof PresentationProperties | "_tag" | "message"]?: never;
+    };
+    /**
+     * What traces and error reports record beside the tag. A fixed description is recorded as is; a
+     * presentation derived from fields is recorded only through this, from fixed text and closed
+     * fields, never a value the caller chose, an app's text or a service's reply. Without it the
+     * error is recorded by its tag alone.
+     */
+    readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
+} & (ErrorPresentation | {
+    readonly presentation: (fields: Schema.Struct.Type<Fields>) => ErrorPresentation;
+});
+declare const RecoveryField: Schema.decodeTo<Schema.optionalKey<Schema.Struct<{
+    readonly action: Schema.String;
+    readonly instructions: Schema.String;
+}>>, Schema.Struct<{
+    readonly action: Schema.String;
+    readonly instructions: Schema.String;
+}>, never, never>;
+type DerivedFields = {
+    readonly message: typeof MessageField;
+    readonly recovery: typeof RecoveryField;
+};
+type ErrorFields<Tag extends string, Fields extends Schema.Struct.Fields> = Omit<Schema.TaggedStruct<Tag, Fields & DerivedFields>, "~type.make.in"> & {
+    readonly "~type.make.in": Schema.TaggedStruct<Tag, Fields>["~type.make.in"];
+};
+type ErrorClass<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Class<Schema.Struct.Type<Fields> & UserFacingError & {
+    readonly _tag: Tag;
+}, ErrorFields<Tag, Fields>, UserFacingError>;
+/** Define a schema-backed error with no payload. Its tag becomes its public error code. */
+declare function define<const Tag extends string>(definition: Header<Tag> & ErrorPresentation): ErrorClass<Tag, {}>;
+/** Define a schema-backed error whose safe presentation can depend on its parsed fields. */
+declare function define<const Tag extends string, const Fields extends Schema.Struct.Fields>(definition: Definition<Tag, Fields>): ErrorClass<Tag, Fields>;
+/** Define the schema, error constructor, user copy, and agent recovery together. */
+export declare const UserFacingError: {
+    define: typeof define;
+    is: (value: unknown) => value is UserFacingError;
+};
+/** Defects get a safe explanation without exposing an arbitrary cause. */
+export declare const UnexpectedError: ErrorClass<"UnexpectedError", {}>;
+export {};

package/js/chunk-EG72MSVK.js

@@ -1,16 +0,0 @@
-import {
-  Predicate_exports
-} from "./chunk-IFJU5SYQ.js";
-
-// ../utils/src/recorded-message.ts
-var RecordedMessage = /* @__PURE__ */ Symbol.for("@executor-js/utils/RecordedMessage");
-var recordedMessage = (error) => {
-  if (!Predicate_exports.hasProperty(error, RecordedMessage)) return void 0;
-  const message = error[RecordedMessage];
-  return typeof message === "string" ? message : void 0;
-};
-
-export {
-  RecordedMessage,
-  recordedMessage
-};