apps 0.0.1-beta.0 → 0.0.1-beta.10

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/app-data/src/contracts/database.d.ts

@@ -157,6 +157,33 @@ export declare const DatabaseLimits: Schema.Struct<{
 export type DatabaseLimits = typeof DatabaseLimits.Type;
 /** Current per-invocation budgets, shared by every database adapter. */
 export declare const defaultDatabaseLimits: DatabaseLimits;
+/**
+ * The budget a query or mutation exhausted. `pageSize` bounds one take(n) or paginate call;
+ * `valueBytes` bounds one stored row; the rest accumulate across the whole invocation.
+ */
+export declare const DatabaseLimit: Schema.Literals<readonly ["scanCalls", "directGets", "rowsRead", "rowsReturned", "pageSize", "bytesRead", "writes", "valueBytes"]>;
+export type DatabaseLimit = typeof DatabaseLimit.Type;
+declare const DatabaseLimitExceeded_base: Schema.Class<DatabaseLimitExceeded, Schema.TaggedStruct<"DatabaseLimitExceeded", {
+    readonly limit: Schema.Literals<readonly ["scanCalls", "directGets", "rowsRead", "rowsReturned", "pageSize", "bytesRead", "writes", "valueBytes"]>;
+    readonly maximum: Schema.Int;
+    readonly requested: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** A query or mutation exceeded one of its database budgets. Nothing it wrote is committed. */
+export declare class DatabaseLimitExceeded extends DatabaseLimitExceeded_base {
+    get message(): string;
+}
+/** Host-owned row metadata that authored tables cannot declare. */
+export declare const reservedFieldNames: readonly ["id", "createdAt", "updatedAt"];
+declare const DatabaseFieldReserved_base: Schema.Class<DatabaseFieldReserved, Schema.TaggedStruct<"DatabaseFieldReserved", {
+    readonly table: Schema.String;
+    readonly field: Schema.Literals<readonly ["id", "createdAt", "updatedAt"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A table declared a field the host adds to every row. */
+export declare class DatabaseFieldReserved extends DatabaseFieldReserved_base {
+    get message(): string;
+}
+/** Failures a database session reports to authored code and its host. */
+export type DatabaseError = AppDatabaseError | DatabaseLimitExceeded;
 /** Host resource bounds outside an individual database transaction. Durations are milliseconds. */
 export declare const DatabaseRuntimeLimits: Schema.Struct<{
     readonly maxCursorChars: Schema.Int;
@@ -173,21 +200,21 @@ export declare const defaultDatabaseRuntimeLimits: {
 /** The host binds one database and read/write authority for the entire invocation. */
 export interface DatabaseSession {
     /** Host-only idempotency receipt, committed atomically with the mutation and validated result. */
-    readonly once: <E, R>(key: string, fingerprint: string, work: () => Effect.Effect<Schema.Json, E, R>) => Effect.Effect<Schema.Json, E | AppDatabaseError, R>;
+    readonly once: <E, R>(key: string, fingerprint: string, work: () => Effect.Effect<Schema.Json, E, R>) => Effect.Effect<Schema.Json, E | DatabaseError, R>;
     readonly readTables: ReadonlySet<string>;
     readonly changedTables: ReadonlySet<string>;
-    readonly execute: (operation: DatabaseOperation) => Effect.Effect<OperationResult, AppDatabaseError>;
+    readonly execute: (operation: DatabaseOperation) => Effect.Effect<OperationResult, DatabaseError>;
 }
 /** Native operation scope owns snapshot consistency, write rollback and commit notifications. */
 export interface AppDatabase {
     readonly schema: DatabaseSchema;
     readonly schemaHash: string;
-    readonly read: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
-    readonly mutate: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
+    readonly read: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | DatabaseError, R>;
+    readonly mutate: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | DatabaseError, R>;
 }
 /** Product-independent app partitions. A host supplies persistent storage; callers never choose filenames. */
 export interface AppDatabases {
-    readonly read: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
-    readonly mutate: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
+    readonly read: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError>;
+    readonly mutate: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | DatabaseError>;
 }
 export {};

package/types/app-data/src/implementation/schema.d.ts

@@ -1,6 +1,6 @@
 /** Validate declarations and write values before touching SQLite. */
 import { Effect } from "effect";
-import { AppDatabaseError, DatabaseSchema, RowMetadata, type Field, type Row, type Scalar, type Table } from "../contracts/database.js";
+import { AppDatabaseError, DatabaseFieldReserved, DatabaseSchema, RowMetadata, type Field, type Row, type Scalar, type Table } from "../contracts/database.js";
 /** Built-in creation ordering and stable tie-breakers apply to every index. */
 export declare const indexesFor: (table: Table) => {
     name: string;
@@ -11,22 +11,7 @@ export declare const fieldFor: (table: Table, name: string) => Field | undefined
 /** Finite numbers and well-formed strings keep JSON and index ordering consistent. */
 export declare const validScalar: (field: Field, value: unknown) => value is Scalar;
 /** Parse the whole schema, including references and composite-index definitions. */
-export declare const parseDatabaseSchema: (input: unknown) => Effect.Effect<{
-    readonly [x: string]: {
-        readonly fields: {
-            readonly [x: string]: {
-                readonly kind: "string" | "number" | "boolean" | "id" | "userId";
-                readonly optional?: boolean | undefined;
-                readonly default?: string | number | boolean | undefined;
-                readonly references?: string | undefined;
-            };
-        };
-        readonly indexes: readonly {
-            readonly name: string;
-            readonly fields: readonly [string, ...string[]];
-        }[];
-    };
-}, AppDatabaseError, never>;
+export declare const parseDatabaseSchema: (input: unknown) => Effect.Effect<DatabaseSchema, AppDatabaseError | DatabaseFieldReserved>;
 /** Canonical ordering for schema fingerprints and query-bound cursors. */
 export declare const canonicalSchema: (schema: DatabaseSchema) => string;
 /** Inserts apply declared defaults; updates reject unknown/metadata fields and clear optional values with null. */

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,8 +1,8 @@
+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";
 import type { OperationSchedule } from "./schedules.js";
-import type { AppOperation } from "./operations.js";
 import type { AccountOf, AuthMethods, ManyAccounts, Provider } from "./provider.js";
 import type { AppWorkflow, WorkflowReads } from "./workflows.js";
 import type { Elicit } from "./elicitation.js";
@@ -10,12 +10,16 @@ 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> {
+    /** The app's root router. Its keys form tool paths such as `issues.list`. */
+    readonly tools?: import("./router.js").AppRouter | import("./router.js").DynamicRouter;
+    /** 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;
     }>>;
-    readonly queries?: Readonly<Record<string, AppOperation>>;
-    readonly mutations?: Readonly<Record<string, AppOperation>>;
     readonly webhooks?: Readonly<Record<string, {
         readonly account: string;
         readonly config: Schema.Decoder<unknown>;
@@ -31,11 +35,19 @@ 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. */
     readonly elicit: Elicit;
-    /** Invocation-owned HTTP requests with trace propagation and host cancellation. */
+    /**
+     * Invocation-owned HTTP requests with trace propagation and host cancellation. It lasts until the
+     * invocation and every app cache refresh it started in the background have ended, so a catalog
+     * loader given this fetch can refresh after the reply.
+     */
     readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
     /** Host cancellation for this invocation. Pass it to fetch and other interruptible APIs. */
     readonly signal: AbortSignal;

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/failure.d.ts

@@ -0,0 +1,25 @@
+/** Failure detail that crosses the runtime boundary to the app's own caller. */
+import { Schema } from "effect";
+/** Longest failure message carried across the runtime boundary. */
+export declare const maxFailureMessageLength = 2048;
+/**
+ * `app` for errors thrown by authored code, `storage` for app data failures the host raised, and
+ * `service` for an external API the app called through a framework helper.
+ */
+export declare const FailureSource: Schema.Literals<readonly ["app", "storage", "service"]>;
+/** The thrown error's name, such as `TypeError`, or the host error's tag. */
+export declare const FailureName: Schema.String;
+/** A stable host failure code, such as an app data reason. */
+export declare const FailureCode: Schema.String;
+/** Bounded, with the invocation's account secrets replaced. */
+export declare const FailureMessage: Schema.String;
+/**
+ * The error an app's own code raised, or the specific host failure it hit. Stacks and cause
+ * values stay private. Builds from before these fields existed send none.
+ */
+export declare const FailureDetail: {
+    source: Schema.optionalKey<Schema.Literals<readonly ["app", "storage", "service"]>>;
+    errorName: Schema.optionalKey<Schema.String>;
+    code: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+};

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 {};