apps 0.0.1-beta.0 → 0.0.1-beta.2

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

@@ -0,0 +1,119 @@
+/** Serializable cache protocol. Hosts bind the application and build namespace separately. */
+import { Schema, type Effect } from "effect";
+declare const CacheError_base: Schema.Class<CacheError, Schema.TaggedStruct<"CacheError", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "storage", "invalid", "capacity", "timeout"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Expected cache failures never include keys, values or upstream exception text. */
+export declare class CacheError extends CacheError_base {
+}
+/** Bounded defaults shared by loaders and persistent adapters. */
+export declare const cacheLimits: {
+    readonly keyBytes: 8192;
+    readonly entryBytes: 2000000;
+    readonly batchBytes: 8000000;
+    readonly batchEntries: 128;
+    readonly totalBytes: 128000000;
+    readonly totalEntries: 100000;
+    readonly retentionMs: number;
+    readonly loadTimeoutMs: 90000;
+    /**
+     * A loader's lease lapses this long after its host last renewed it. Hosts renew every
+     * `renewMs` while the invocation that claimed it runs, so a stalled or lost holder frees the
+     * key well inside an MCP execute budget.
+     */
+    readonly leaseMs: 15000;
+    readonly renewMs: 5000;
+    /** The longest a caller waits on another loader before loading for itself without publishing. */
+    readonly waitMs: 10000;
+    /** Bound for one command to a host store; a lost reply fails instead of holding its caller. */
+    readonly commandTimeoutMs: 10000;
+};
+/** Stored values carry a version independent of their freshness clock. */
+export declare const CacheEntry: Schema.Struct<{
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly version: Schema.String;
+    readonly freshUntil: Schema.Finite;
+    readonly staleUntil: Schema.Finite;
+}>;
+/** Decoded cache value envelope. */
+export type CacheEntry = typeof CacheEntry.Type;
+/** The current entry, and a lease when this caller now owns its load. */
+export declare const CacheAcquired: Schema.Struct<{
+    readonly entry: Schema.NullOr<Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly version: Schema.String;
+        readonly freshUntil: Schema.Finite;
+        readonly staleUntil: Schema.Finite;
+    }>>;
+    readonly lease: Schema.NullOr<Schema.String>;
+}>;
+/**
+ * Publication requires the lease acquired against the previously observed version.
+ * `acquire` reads one entry and claims its load in the same transaction, so a cache
+ * miss costs one round trip. `read` and `claim` remain for builds retained before it.
+ */
+export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"read">;
+    readonly keys: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"acquire">;
+    readonly key: Schema.String;
+    /** Claim even a fresh entry, as an explicit refresh does. */
+    readonly refresh: Schema.Boolean;
+    /** Claim only while the entry still has this version. Absent accepts the current one. */
+    readonly version: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"claim">;
+    readonly key: Schema.String;
+    readonly version: Schema.NullOr<Schema.String>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"publish">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+    readonly entry: Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly version: Schema.String;
+        readonly freshUntil: Schema.Finite;
+        readonly staleUntil: Schema.Finite;
+    }>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"release">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"renew">;
+    readonly key: Schema.String;
+    readonly lease: Schema.String;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"write">;
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly entry: Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly version: Schema.String;
+            readonly freshUntil: Schema.Finite;
+            readonly staleUntil: Schema.Finite;
+        }>;
+    }>>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"invalidate">;
+    readonly key: Schema.String;
+}>]>;
+/** Parsed host command; namespaces cannot be selected by app code. */
+export type CacheCommand = typeof CacheCommand.Type;
+/** Replies remain JSON across Worker RPC and are decoded by each caller. */
+export type CacheTransport = (command: CacheCommand) => Effect.Effect<Schema.Json, CacheError>;
+/**
+ * Whether a command replaced or removed retained data: a published refresh, a direct write or an
+ * invalidation. Hosts report these so results evaluated from the earlier data are not reused.
+ */
+export declare const changesCache: (command: unknown) => boolean;
+/** Safe protocol envelope used at process boundaries. */
+export declare const CacheReply: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof CacheError;
+}>]>;
+export {};

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

@@ -0,0 +1,93 @@
+/** Portable Effect cache mechanics. Adapters own storage and the background task lifetime. */
+import { Duration, Effect, Schema } from "effect";
+import { CacheError, type CacheTransport } from "./contracts/cache.js";
+export * from "./contracts/cache.js";
+/** Hash key material before storage or transport; keys and credential scope never enter telemetry. */
+export declare const cacheKey: (key: unknown) => Effect.Effect<string, CacheError, never>;
+/** A cache hit is decoded with the caller's schema. Loader failures are never cached. */
+export interface CacheGet<A> {
+    readonly key: Schema.Json;
+    readonly schema: Schema.Decoder<A>;
+    readonly freshFor: Duration.Input;
+    readonly staleFor?: Duration.Input;
+    readonly load: Effect.Effect<A, unknown>;
+}
+/** Create a scoped cache client; a background runner must retain all task resources until completion. */
+export declare const makeCache: (host: CacheTransport, background: (task: Effect.Effect<void, unknown>) => Effect.Effect<void>, scope?: Schema.Json, 
+/** The caller's own deadline, when the host supplies one. Waiting never runs past it. */
+deadline?: number) => {
+    /** Read arbitrary retained JSON entries without initiating a refresh. Missing and null are distinct. */
+    read: (keys: readonly Schema.Json[]) => Effect.Effect<readonly ({
+        readonly value: Schema.Json;
+        readonly version: string;
+        readonly freshUntil: number;
+        readonly staleUntil: number;
+    } | null)[], CacheError, never>;
+    /** Publish bounded immutable parts before publishing the manifest that references them. */
+    write: (entries: readonly {
+        readonly key: Schema.Json;
+        readonly value: Schema.Json;
+    }[], 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. */
+    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>;
+};
+/**
+ * Host-side lease ownership for one app invocation. Leases the invocation claims are renewed while
+ * it runs, so a slow load keeps its key, and released when the host ends the invocation, including
+ * interrupted and cancelled ones and loads whose own release never arrived. A holder that stops
+ * running, or whose store channel stops answering, loses its lease within `leaseMs`.
+ */
+export declare const holdLeases: (transport: CacheTransport) => Effect.Effect<{
+    /** Use for every command of the invocation. Each command is bounded by `commandTimeoutMs`. */
+    transport: (input: {
+        readonly operation: "read";
+        readonly keys: readonly string[];
+    } | {
+        readonly operation: "acquire";
+        readonly key: string;
+        readonly refresh: boolean;
+        readonly version?: string | null;
+    } | {
+        readonly operation: "claim";
+        readonly key: string;
+        readonly version: string | null;
+    } | {
+        readonly operation: "publish";
+        readonly key: string;
+        readonly lease: string;
+        readonly entry: {
+            readonly value: Schema.Json;
+            readonly version: string;
+            readonly freshUntil: number;
+            readonly staleUntil: number;
+        };
+    } | {
+        readonly operation: "release";
+        readonly key: string;
+        readonly lease: string;
+    } | {
+        readonly operation: "renew";
+        readonly key: string;
+        readonly lease: string;
+    } | {
+        readonly operation: "write";
+        readonly entries: readonly {
+            readonly key: string;
+            readonly entry: {
+                readonly value: Schema.Json;
+                readonly version: string;
+                readonly freshUntil: number;
+                readonly staleUntil: number;
+            };
+        }[];
+    } | {
+        readonly operation: "invalidate";
+        readonly key: string;
+    }) => Effect.Effect<Schema.Json, CacheError, never>;
+    /** Stop renewing and release every lease the invocation still holds. */
+    close: Effect.Effect<void, never, never>;
+}, never, never>;

package/types/apps/src/contracts/api-response-error.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+/** Bounded recovery a declared API error published for its caller: a short next step and agent guidance. */
+export declare const ApiErrorRecovery: Schema.Struct<{
+    readonly action: Schema.NonEmptyString;
+    readonly instructions: Schema.NonEmptyString;
+}>;
+/** Recovery copied from an error response body; extra keys are dropped on decode. */
+export type ApiErrorRecovery = typeof ApiErrorRecovery.Type;
+/** Bounded public fields from a response matching its declared API error schema. */
+export declare const ApiErrorResponse: Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.NonEmptyString;
+    readonly recovery: Schema.optionalKey<Schema.Struct<{
+        readonly action: Schema.NonEmptyString;
+        readonly instructions: Schema.NonEmptyString;
+    }>>;
+}>;
+/** Safe projection of a response matching a declared API error schema. */
+export type ApiErrorResponse = typeof ApiErrorResponse.Type;
+declare const OpenapiResponseError_base: Schema.Class<OpenapiResponseError, Schema.TaggedStruct<"OpenapiResponseError", {
+    readonly code: Schema.NonEmptyString;
+    readonly status: Schema.Int;
+    readonly message: Schema.NonEmptyString;
+    readonly recovery: Schema.optionalKey<Schema.Struct<{
+        readonly action: Schema.NonEmptyString;
+        readonly instructions: Schema.NonEmptyString;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** A validated OpenAPI failure with its declared message or static schema explanation. */
+export declare class OpenapiResponseError extends OpenapiResponseError_base {
+}
+/** Error response reads have independent byte and time bounds, including chunked bodies. */
+export declare const OpenapiErrorLimits: Schema.Struct<{
+    readonly maxBodyBytes: Schema.Int;
+    readonly readTimeoutMs: Schema.Int;
+}>;
+/** Stop reading on overflow or timeout and keep the generic HTTP failure. */
+export declare const defaultOpenapiErrorLimits: {
+    readonly maxBodyBytes: number;
+    readonly readTimeoutMs: number;
+};
+export {};

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

@@ -1,3 +1,4 @@
+import type { AppSkillSource, SkillFile } from "./skills.js";
 import type { DatabaseDefinition } from "./storage.js";
 /** Native app contracts; factories and handlers compose in the host's Effect runtime. */
 import { type Effect, Schema } from "effect";
@@ -10,6 +11,12 @@ import type { Elicit } from "./elicitation.js";
 type Handler<Context> = (context: Context, input: never) => Effect.Effect<unknown, unknown>;
 /** App capabilities share one account context. Package metadata belongs in package.json. */
 export interface AppDefinition<Context> {
+    /** Optional dynamic tools; resolution does not enumerate the catalog. */
+    readonly dynamicTools?: import("./dynamic-tools.js").DynamicTools;
+    /** Omission reads packaged skills/. An explicit catalog replaces that default, including []. */
+    readonly skills?: readonly AppSkillSource[];
+    /** Optional lazy skills, added to the static catalog. Only skill reads call them. */
+    readonly dynamicSkills?: import("./dynamic-skills.js").DynamicSkills;
     readonly workflows?: Readonly<Record<string, AppWorkflow>>;
     readonly schedules?: Readonly<Record<string, Omit<OperationSchedule, "name"> & {
         readonly tool: string;
@@ -31,6 +38,10 @@ export type AccountSlots = Readonly<Record<string, Provider<AuthMethods> | ManyA
 type AccountsFor<Slot> = Slot extends ManyAccounts<infer Auth> ? readonly AccountOf<Provider<Auth>>[] : AccountOf<Slot>;
 /** Current credentials for one invocation. Never retained in source or build output. */
 export interface BoundContext<Slots extends AccountSlots> {
+    /** Explicit app/build-scoped caching. Account-specific loaders opt into forAccount. */
+    readonly cache: import("./cache.js").AppCache;
+    /** Text files retained in this deployment. Paths are package-relative, never host filesystem paths. */
+    readonly files: readonly SkillFile[];
     /** Read-only run management, bound to this configured app. */
     readonly workflows: WorkflowReads;
     /** Ask for user input during this tool call. Unavailable during discovery and after the invocation closes. */

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

@@ -0,0 +1,44 @@
+/** Author cache API; schemas parse persisted values before they re-enter app code. */
+import type { Duration, Effect } from "effect";
+import type { CacheTransport } from "../../../app-cache/src/contracts/cache.js";
+import type { Schema } from "../implementation/schema.js";
+import type { JsonValue } from "./schema.js";
+/** A cache loader owns its own cancellation and HTTP capability, including during SWR. */
+export interface CacheLoadContext {
+    readonly cache: AppCache;
+    readonly signal: AbortSignal;
+    readonly fetch: typeof globalThis.fetch;
+}
+/** Load options shared by normal reads and explicit refreshes. */
+export interface CacheGetOptions<A> {
+    readonly key: JsonValue;
+    readonly schema: Schema<A, boolean>;
+    readonly freshFor: Duration.Input;
+    readonly staleFor?: Duration.Input;
+    readonly load: (context: CacheLoadContext) => Promise<A>;
+}
+/** Cache keys describe every input that affects the value; the host adds app/build isolation. */
+export interface AppCache {
+    readonly get: <A>(options: CacheGetOptions<A>) => Promise<A>;
+    /** Await a fresh load, coalescing concurrent refreshes and retaining the previous value on failure. */
+    readonly revalidate: <A>(options: CacheGetOptions<A>) => Promise<A>;
+    readonly read: <A>(key: JsonValue, schema: Schema<A, boolean>) => Promise<A | undefined>;
+    readonly readMany: <A>(keys: readonly JsonValue[], schema: Schema<A, boolean>) => Promise<readonly (A | undefined)[]>;
+    readonly write: (entries: readonly {
+        readonly key: JsonValue;
+        readonly value: JsonValue;
+    }[], retention: Duration.Input) => Promise<void>;
+    readonly invalidate: (key: JsonValue) => Promise<void>;
+    /**
+     * Scope entries to a bound account and its credential generation. Token renewal keeps the
+     * entries; reconnecting or replacing the account's credentials starts an empty scope.
+     */
+    readonly forAccount: (account: {
+        readonly id: string;
+    }) => AppCache;
+}
+/** Trusted storage and background ownership; never accepted from request JSON. */
+export interface HostCache {
+    readonly transport: CacheTransport;
+    readonly background: (task: Effect.Effect<void, unknown>) => Effect.Effect<void>;
+}

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

@@ -0,0 +1,10 @@
+/** Lazy skill loading, shaped like dynamic tools. Only skill reads call it. */
+import type { Effect } from "effect";
+import type { AppSkillSource } from "./skills.js";
+/**
+ * `list` returns complete skills, including their files, added to the static catalog. Every
+ * skill read loads the full catalog. Names must not repeat across both catalogs.
+ */
+export interface DynamicSkills {
+    readonly list: () => Effect.Effect<readonly AppSkillSource[], unknown>;
+}

package/types/apps/src/contracts/dynamic-tools.d.ts

@@ -0,0 +1,13 @@
+/** Lazy operation discovery and resolution. Executables remain invocation-owned. */
+import type { Effect } from "effect";
+import type { HostedTool, HostedToolSummary } from "./host.js";
+import type { AppOperation } from "./operations.js";
+/** Tool names include their queries./mutations. prefix. Resolution never requires listing. */
+export interface DynamicTools {
+    readonly list: () => Effect.Effect<readonly HostedTool[], unknown>;
+    readonly resolve: (name: string) => Effect.Effect<AppOperation | undefined, unknown>;
+    /** Names and descriptions without schemas. Omitted sources reduce list(). */
+    readonly summaries?: () => Effect.Effect<readonly HostedToolSummary[], unknown>;
+    /** One tool's full metadata without listing. Omitted sources search list(). */
+    readonly describe?: (name: string) => Effect.Effect<HostedTool | undefined, unknown>;
+}

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

@@ -1,3 +1,4 @@
+import type { ProviderError } from "./provider-error.js";
 /** GraphQL discovery contracts. Catalogs are evaluated with the selected account. */
 import { Schema, type Effect } from "effect";
 import { type JsonValue } from "./schema.js";
@@ -15,6 +16,7 @@ export declare const defaultGraphqlClientLimits: {
 /** Endpoint and credential snapshot for one app evaluation. */
 export declare const GraphqlToolsOptions: Schema.Struct<{
     readonly url: Schema.String;
+    readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
     readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
     readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
     readonly timeoutMs: Schema.optional<Schema.Int>;
@@ -95,8 +97,23 @@ export interface GraphqlTool {
     readonly description: string;
     readonly readOnly: boolean;
     readonly input: Schema.Decoder<JsonValue>;
-    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError>;
+    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError>;
 }
 /** One tool per root field; subscriptions require a separate long-lived host. */
 export type GraphqlTools = Readonly<Record<string, GraphqlTool>>;
+/** Persisted execution data for one root field; no credentials or executable schema. */
+export declare const GraphqlToolDefinition: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.Literals<readonly ["query", "mutation"]>;
+    readonly field: Schema.String;
+    readonly description: Schema.String;
+    readonly arguments: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly type: Schema.String;
+    }>>;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly composite: Schema.Boolean;
+    readonly selection: Schema.String;
+}>;
+export type GraphqlToolDefinition = typeof GraphqlToolDefinition.Type;
 export {};