apps 0.0.1-beta.41 → 0.0.1-beta.42

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. */