apps 0.0.1-beta.41 → 0.0.1-beta.43

package/types/app-cache/src/index.d.ts

@@ -10,6 +10,12 @@ export interface CacheGet<A> {
     readonly schema: Schema.Decoder<A>;
     readonly freshFor: Duration.Input;
     readonly staleFor?: Duration.Input;
+    /**
+     * What a read does with a value past `freshFor` and within `staleFor`. `serve`, the default,
+     * returns it while one background load replaces it. `revalidate` awaits that load first, like a
+     * miss; the value stays readable to the load, which can confirm it instead of rebuilding it.
+     */
+    readonly stale?: "serve" | "revalidate";
     readonly load: Effect.Effect<A, unknown>;
 }
 /** Create a scoped cache client; a background runner must retain all task resources until completion. */
@@ -30,7 +36,10 @@ deadline?: number) => {
     }[], retention: Duration.Input) => Effect.Effect<void, CacheError, never>;
     /** Revoke retained data and any loader's right to publish its in-flight result. */
     invalidate: (key: Schema.Json) => Effect.Effect<void, CacheError, never>;
-    /** Read fresh data, refresh stale data in the background, or wait for the lease owner. */
+    /**
+     * Read fresh data, refresh stale data in the background (or first, with `stale: "revalidate"`),
+     * or wait for the lease owner.
+     */
     get: <A>(options: CacheGet<A>) => Effect.Effect<A, unknown, never>;
     /** Force one awaited refresh without removing the retained value. Concurrent refreshes share a load. */
     revalidate: <A>(options: CacheGet<A>) => Effect.Effect<A, unknown, never>;

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

@@ -15,6 +15,12 @@ export interface CacheGetOptions<A> {
     readonly schema: Schema<A, boolean>;
     readonly freshFor: Duration.Input;
     readonly staleFor?: Duration.Input;
+    /**
+     * Past `freshFor`, `serve` (the default) returns the kept value while `load` replaces it in the
+     * background. `revalidate` awaits `load` first; the kept value stays readable with `read`, so
+     * the loader can confirm it with the source instead of rebuilding it.
+     */
+    readonly stale?: "serve" | "revalidate";
     readonly load: (context: CacheLoadContext) => Promise<A>;
 }
 /** Cache keys describe every input that affects the value; the host adds app/build isolation. */

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

@@ -98,6 +98,8 @@ export declare const skillLoadLimits: {
     readonly fileBytes: 2000000;
     readonly totalBytes: 20000000;
     readonly concurrency: 8;
+    /** The request that checks whether a kept catalog's publication changed. */
+    readonly checkMillis: 5000;
 };
 /** Invocation-owned transport and cancellation, supplied by the app context. */
 export interface SkillTransport {
@@ -109,14 +111,19 @@ export interface SkillReaderOptions extends SkillTransport {
     readonly service: string;
 }
 /**
- * Catalog reuse shared by remote skill loaders, with the same policy as MCP tool catalogs. Pass
- * `ctx.cache` to keep the loaded catalog; without it every read fetches the source again.
+ * Catalog reuse shared by remote skill loaders. Pass `ctx.cache` to keep the loaded catalog;
+ * without it every read fetches the source again. Unlike an MCP tool catalog, a skill catalog
+ * past `freshFor` is not served while it refreshes: the read first asks the source whether its
+ * publication changed, so agents never read skills that a refresh replaces moments later.
  */
 export interface SkillCacheOptions {
     readonly cache?: import("./cache.js").AppCache;
-    /** Reuse the catalog for this duration. Defaults to five minutes. */
+    /** Reuse the catalog without asking the source for this duration. Defaults to five minutes. */
     readonly freshFor?: import("effect").Duration.Input;
-    /** Serve the retained catalog while refreshing. Defaults to one day. */
+    /**
+     * Keep the catalog this long after `freshFor`. A read then confirms it with one request and
+     * loads the files again only when the publication changed. Defaults to one day.
+     */
     readonly staleFor?: import("effect").Duration.Input;
 }
 /**
@@ -133,7 +140,7 @@ export type GitHubSkillsAccount = import("./cache.js").AccountCredential<{
 }>;
 /**
  * A GitHub repository and an optional immutable commit, tag or branch. With a cache, a branch or
- * tag is resolved again when the catalog refreshes, and each commit's file list is kept.
+ * tag is resolved again once the catalog is past `freshFor`, and each commit's file list is kept.
  */
 export type GitHubSkillsOptions = SkillTransport & SkillCacheOptions & GitHubSkillsAccount & {
     readonly repo: string;

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

@@ -34,6 +34,11 @@ export interface CatalogLoad<A> {
     readonly tools: readonly A[];
     readonly header?: JsonObject;
 }
+/** The catalog a refresh replaces, read only when its loader asks for it. */
+export interface KeptCatalog<A> {
+    readonly header: JsonObject | undefined;
+    readonly tools: Effect.Effect<readonly A[], unknown>;
+}
 export declare const catalogCache: <A extends {
     readonly name: string;
 }, S>(options: Omit<CatalogCacheOptions, "cache"> & {
@@ -46,7 +51,13 @@ export declare const catalogCache: <A extends {
         readonly schema: Schema.Decoder<S>;
         readonly of: (tool: A) => S;
     };
-    readonly load: (context?: CacheLoadContext) => Effect.Effect<CatalogLoad<A>, unknown>;
+    /** Past `freshFor`, serve the kept catalog while refreshing, or refresh first. */
+    readonly stale?: "serve" | "revalidate";
+    /**
+     * Load the catalog. A refresh also gets the catalog it replaces, if one is kept, so a source
+     * that can confirm it is unchanged need not load it again.
+     */
+    readonly load: (context?: CacheLoadContext, kept?: Effect.Effect<KeptCatalog<A> | undefined, unknown>) => Effect.Effect<CatalogLoad<A>, unknown>;
 }) => Effect.Effect<{
     list: () => Effect.Effect<readonly A[], unknown, never>;
     /** The record stored with the current revision, if the source supplied one. */

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/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/user-facing-error.d.ts

@@ -0,0 +1,81 @@
+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 instead of the description, when the description 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;
+} & (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 {};