apps 0.0.1-beta.35 → 0.0.1-beta.37

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

@@ -79,11 +79,16 @@ declare const SkillLoadFailed_base: Schema.Class<SkillLoadFailed, Schema.TaggedS
     readonly reason: Schema.Literals<readonly ["source", "request", "rate_limited", "document", "limit", "changed", "encoding"]>;
     readonly message: Schema.optional<Schema.String>;
     readonly status: Schema.optional<Schema.Int>;
+    readonly missing: Schema.optional<Schema.Literals<readonly ["repository", "ref"]>>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A skill loader failure shown to people. `message` is the explanation they read; write it for
  * them and never include URLs, tokens or response bodies. `reason` selects the title and whether
  * a retry can help. Custom loaders throw this error to get the same presentation as built-ins.
+ * With `source`, `missing` names what the service's answer points to as missing: the `repository`,
+ * or the branch or tag (`ref`). It may be missing, or not readable with the request's credentials.
+ * Without it, the source's settings or the paths it lists are not valid.
+ * These fields choose the explanation; they never show that the failure lies outside Executor.
  */
 export declare class SkillLoadFailed extends SkillLoadFailed_base {
 }

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/apps/src/implementation/failure-detail.d.ts

@@ -1,6 +1,5 @@
 import { Option, Redacted } from "effect";
-import type { ResolvedAccounts } from "../contracts/host.js";
-import { McpError } from "../contracts/mcp.js";
+import { McpError as HostMcpError, SkillLoadFailed as HostSkillLoadFailed, type ResolvedAccounts } from "../contracts/host.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. */
@@ -34,7 +33,9 @@ export declare const leavingProviderError: (error: ProviderError, secrets: reado
  * 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>;
+export declare const parseMcpError: (error: unknown, secrets: readonly string[]) => Option.Option<HostMcpError>;
+/** Rebuild only the allowlisted skill loader fields from an author-visible rejection. */
+export declare const parseSkillLoadFailed: (error: unknown) => Option.Option<HostSkillLoadFailed>;
 /** `Name: message` for any thrown value, before redaction. */
 export declare const describeFailure: (error: unknown) => string;
 /**

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

@@ -46,8 +46,8 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly description?: string;
             readonly version?: string;
             readonly name?: string;
-            readonly title?: string;
             readonly instructions?: string;
+            readonly title?: string;
             readonly icons?: readonly {
                 readonly src: string;
                 readonly mimeType?: string;

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

@@ -30,8 +30,8 @@ export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.
             readonly description?: string;
             readonly version?: string;
             readonly name?: string;
-            readonly title?: string;
             readonly instructions?: string;
+            readonly title?: string;
             readonly icons?: readonly {
                 readonly src: string;
                 readonly mimeType?: string;

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

@@ -68,7 +68,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "QUERY";
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;

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

@@ -6,7 +6,6 @@ import { Effect, Schema } from "effect";
 import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
-import { SkillLoadFailed } from "../contracts/skills.js";
 import type { OperationSchedule } from "../contracts/schedules.js";
 /**
  * Keep only a failure's safe fields. Anything unrecognized becomes an evaluation failure with the
@@ -189,7 +188,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
     routers: {
         readonly path: string;
         readonly description?: string;
-        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError;
+        readonly error?: import("../index.js").ProviderError | HostDeclarationInvalid | HostEvaluationFailed | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed;
         readonly title?: string;
         readonly tags?: {
             readonly [x: string]: string;
@@ -202,7 +201,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
         }[];
         readonly skill?: string;
     }[];
-}, import("../index.js").ProviderError | SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed | import("../mcp.js").McpError, never>;
+}, import("../index.js").ProviderError | HostDeclarationInvalid | HostEvaluationFailed | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed, 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/skills.d.ts

@@ -4,21 +4,21 @@ import { NetworkRefused } from "../contracts/network.js";
 import { ProviderError } from "../contracts/provider-error.js";
 import { AppSkills, SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
 /** Give every failure without a message one that names the service. */
-export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed, R>) => Effect.Effect<A, SkillLoadFailed, R>;
+export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed | NetworkRefused, R>) => Effect.Effect<A, NetworkRefused | SkillLoadFailed, R>;
 interface ReadRequest {
     readonly headers?: Readonly<Record<string, string>>;
-    /** Describe a refusal by Executor's app network; defaults to the refusal's own message. */
-    readonly refused?: (refused: NetworkRefused) => SkillLoadFailed;
+    /** Describe a refusal by Executor's app network; defaults to the refusal itself. */
+    readonly refused?: (refused: NetworkRefused) => SkillLoadFailed | NetworkRefused;
 }
 /** One loader invocation owns its byte budget and all of its network requests. */
 export declare const reader: (transport: SkillTransport) => Effect.Effect<{
     fetchBytes: (url: string, request?: ReadRequest & {
         readonly body?: Uint8Array;
-    }) => Effect.Effect<Uint8Array<ArrayBuffer>, SkillLoadFailed, never>;
-    read: (url: string, request?: ReadRequest) => Effect.Effect<string, SkillLoadFailed, never>;
-    json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
+    }) => Effect.Effect<Uint8Array<ArrayBuffer>, NetworkRefused | SkillLoadFailed, never>;
+    read: (url: string, request?: ReadRequest) => Effect.Effect<string, NetworkRefused | SkillLoadFailed, never>;
+    json: (url: string) => Effect.Effect<unknown, NetworkRefused | SkillLoadFailed, never>;
 }, never, never>;
-export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<typeof AppSkills.Type, SkillLoadFailed | ProviderError>;
+export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<typeof AppSkills.Type, SkillLoadFailed | NetworkRefused | ProviderError>;
 /** Fetch all indexed files and reject a publication whose index changes during the read. */
 export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
     readonly description: string;
@@ -33,5 +33,5 @@ export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) =>
         readonly [x: string]: string;
     };
     readonly "allowed-tools"?: string;
-}[], SkillLoadFailed, never>;
+}[], NetworkRefused | SkillLoadFailed, never>;
 export {};

package/types/apps/src/skills.d.ts

@@ -66,7 +66,8 @@ export declare const folderSkills: (options: FolderSkillsOptions) => Promise<rea
 }[]>;
 /**
  * Read files for a custom remote skill loader, such as one for GitLab. Reads share one byte
- * budget and reject with the same safe SkillLoadFailed errors as githubSkills, naming `service`.
+ * budget and reject with the same safe SkillLoadFailed errors as githubSkills, naming `service`,
+ * or with `NetworkRefused` when Executor's network refuses a request.
  */
 export declare const skillReader: (options: SkillReaderOptions) => {
     /** Fetch one UTF-8 text file. */

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;