apps 0.0.1-beta.36 → 0.0.1-beta.37

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

@@ -1,5 +1,6 @@
 /** Portable workflow declarations, run views and durable execution capabilities. */
 import { Schema, type Effect } from "effect";
+import { RecordedMessage } from "../../../utils/src/recorded-message.js";
 import { JsonValue } from "./schema.js";
 import type { AppContext, AppRequirements, QueryContext, MutationContext } from "./context.js";
 import type { Operation } from "../implementation/operations.js";
@@ -49,6 +50,11 @@ declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 /** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
+    /**
+     * The step name and error detail are the app's. Its run's owner reads them; telemetry records
+     * only the reason, however the failure was built or decoded.
+     */
+    get [RecordedMessage](): string | undefined;
 }
 /** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {

package/types/telemetry/src/app-records.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the host keeps of the spans and logs an app isolate returns.
+ *
+ * Those records come from whatever framework the app's build bundles, and the app's own code runs
+ * in the same isolate: it can throw any text, name its errors and codes, and rewrite every record
+ * before the isolate returns it. So the host does not filter the records it receives. It builds
+ * new ones from a closed vocabulary: the framework's span names, attributes whose values are
+ * closed sets, counts and status codes, and each exception's kind. Ids, parents and timings are
+ * kept. Everything else, including events other than exceptions, links, status and exception
+ * messages, stacks and log bodies, is dropped or replaced with a fixed sentence.
+ *
+ * The vocabulary is the framework's (`packages/apps`, `app-cache`, `app-data`): host request
+ * operations, failure sources and reasons, MCP and cache attributes. A name or value outside it is
+ * recorded as `unrecognized` or not at all. `bun run check` (`scripts/check-app-telemetry.ts`)
+ * fails when the framework names a span or sets an attribute key this vocabulary does not know.
+ */
+import type { Schema } from "effect";
+type Json = Schema.Json;
+type JsonObject = {
+    readonly [key: string]: Json;
+};
+/** What an exception message, stack or log body from an app isolate records instead. */
+export declare const appText = "Text from the app is not recorded";
+/** The framework's span names, and the libraries' spans it runs. */
+export declare const appSpanNames: ReadonlySet<string>;
+export declare const appSpanAttributeKeys: ReadonlySet<string>;
+/**
+ * Attributes the framework sets whose values the app chooses, such as its tool names, so the host
+ * drops them. `scripts/check-app-telemetry.ts` fails on a framework attribute in neither set.
+ */
+export declare const droppedAppAttributeKeys: ReadonlySet<string>;
+/** The span the host records for one an app isolate returned, or nothing without its timings. */
+export declare const appSpan: (span: JsonObject & {
+    readonly traceId: string;
+    readonly spanId: string;
+}) => JsonObject | undefined;
+/** The log record the host records for one an app isolate returned. */
+export declare const appLog: (log: JsonObject & {
+    readonly traceId?: string | undefined;
+    readonly spanId?: string | undefined;
+}) => JsonObject;
+export {};

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+export declare const recordedCause: <E>(cause: Cause.Cause<E>) => Cause.Cause<unknown>;

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

@@ -23,6 +23,11 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
      * record, so it never includes credentials, upstream response text or submitted values.
      */
     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.
+     */
+    readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
 };
 type ErrorFields<Tag extends string, Fields extends Schema.Struct.Fields> = Omit<Schema.TaggedStruct<Tag, Fields & {
     readonly message: typeof MessageField;

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

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export declare const RecordedMessage: unique symbol;
+/** The fixed sentence an error declares for telemetry, if it declares one. */
+export declare const recordedMessage: (error: unknown) => string | undefined;
+/**
+ * Declare a recorded message on one error that Executor did not define the text of, such as an
+ * error decoded from an app's reply. An error class's own declaration is kept. The error's fields
+ * and wire encoding are unchanged.
+ */
+export declare const recordAs: <E>(error: E, message: string) => E;