apps 0.0.1-beta.1 → 0.0.1-beta.100

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

@@ -2,6 +2,8 @@
 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"]>;
+    /** Which of `cacheLimits` the request exceeded, when one did. */
+    readonly limit: Schema.optionalKey<Schema.Literals<readonly ["keyBytes", "entryBytes", "batchBytes", "batchEntries", "totalBytes", "totalEntries"]>>;
 }>, import("effect/Cause").YieldableError>;
 /** Expected cache failures never include keys, values or upstream exception text. */
 export declare class CacheError extends CacheError_base {
@@ -16,7 +18,17 @@ export declare const cacheLimits: {
     readonly totalEntries: 100000;
     readonly retentionMs: number;
     readonly loadTimeoutMs: 90000;
-    readonly leaseMs: 120000;
+    /**
+     * 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<{
@@ -27,10 +39,47 @@ export declare const CacheEntry: Schema.Struct<{
 }>;
 /** Decoded cache value envelope. */
 export type CacheEntry = typeof CacheEntry.Type;
-/** Publication requires the lease acquired against the previously observed version. */
+/** 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>;
+    /**
+     * The entries of the command's `reads`, in order, read in the same transaction as `entry`.
+     * Absent when the store did not read them: a store that predates them, or reads past the
+     * batch byte bound. The caller then reads them with a separate `read`.
+     */
+    readonly reads: Schema.optionalKey<Schema.$Array<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;
+    }>>>>;
+}>;
+/**
+ * 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>>;
+    /**
+     * Other keys to read in the same transaction, as `read` would, so a caller that needs them
+     * beside the entry makes one round trip. Reading them claims and changes nothing.
+     */
+    readonly reads: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, Schema.Struct<{
     readonly operation: Schema.Literal<"claim">;
     readonly key: Schema.String;
@@ -49,6 +98,10 @@ export declare const CacheCommand: Schema.Union<readonly [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<{
@@ -68,6 +121,11 @@ export declare const CacheCommand: Schema.Union<readonly [Schema.Struct<{
 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>;

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

@@ -10,10 +10,23 @@ 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. */
-export declare const makeCache: (transport: CacheTransport, background: (task: Effect.Effect<void, unknown>) => Effect.Effect<void>, scope?: Schema.Json) => {
+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, 
+/**
+ * Wraps the time this caller waits on another caller's load of the same entry, polls included,
+ * so the host can trace it and count it as waiting rather than as its own work.
+ */
+leaseWait?: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) => {
     /** 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;
@@ -28,8 +41,85 @@ export declare const makeCache: (transport: CacheTransport, background: (task: E
     }[], 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>;
+    /**
+     * `get`, also reading the keys of this scope that `keys` names in the same round trip. `keys`
+     * gets the entry's store key, which is unique to this scope and key, so a caller can remember
+     * what it read under it. `reads` holds their entries, undecoded and in order, when the value
+     * was read from the store; it is undefined when the value was loaded or the store did not read
+     * them, and the caller then reads what it still needs.
+     */
+    getWith: <A>(options: CacheGet<A>, keys: (key: string) => readonly Schema.Json[]) => Effect.Effect<{
+        value: A;
+        key: string;
+        reads: readonly ({
+            readonly value: Schema.Json;
+            readonly version: string;
+            readonly freshUntil: number;
+            readonly staleUntil: number;
+        } | null)[] | undefined;
+    }, 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 reads?: readonly string[];
+    } | {
+        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/apps/src/contracts/api-response-error.d.ts

@@ -1,4 +1,6 @@
 import { Schema } from "effect";
+/** Longest agent guidance an API error's recovery carries. */
+export declare const maxApiErrorInstructionsLength = 4096;
 /** 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;
@@ -6,6 +8,8 @@ export declare const ApiErrorRecovery: Schema.Struct<{
 }>;
 /** Recovery copied from an error response body; extra keys are dropped on decode. */
 export type ApiErrorRecovery = typeof ApiErrorRecovery.Type;
+/** Longest message an API error response carries. */
+export declare const maxApiErrorMessageLength = 4096;
 /** Bounded public fields from a response matching its declared API error schema. */
 export declare const ApiErrorResponse: Schema.Struct<{
     readonly code: Schema.NonEmptyString;

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

@@ -1,9 +1,7 @@
 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";
@@ -11,8 +9,8 @@ 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;
+    /** 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. */
@@ -21,10 +19,8 @@ export interface AppDefinition<Context> {
     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 account: WebhookAccount;
         readonly config: Schema.Decoder<unknown>;
         readonly state: Schema.Decoder<unknown>;
         readonly setup?: import("./webhook-protocol.js").ManualWebhookSetup;
@@ -33,32 +29,82 @@ export interface AppDefinition<Context> {
         readonly unregister?: Handler<Context>;
     }>>;
 }
+/**
+ * Whose accounts a requirement or context names. App accounts are linked for everyone by the app's
+ * managers and fill the requirement for every caller and for the app's background work; user
+ * accounts are the caller's own links. App-scope work, such as an app schedule, has no caller.
+ */
+export type AccountScope = "app" | "user";
+/** The requirement a webhook's source account fills, in its scope. */
+export type WebhookAccount = {
+    readonly app: string;
+} | {
+    readonly user: string;
+};
 /** Named requirements for one account or a collection from a provider. */
 export type AccountSlots = Readonly<Record<string, Provider<AuthMethods> | ManyAccounts<AuthMethods>>>;
+/**
+ * An app's requirements by scope. A requirement name is unique across both scopes, so a host can
+ * name one requirement without its scope.
+ */
+export interface ScopedSlots {
+    readonly app: AccountSlots;
+    readonly user: AccountSlots;
+}
 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> {
+/** One scope's current accounts, by requirement. */
+export type BoundAccounts<Slots extends AccountSlots> = {
+    readonly [Slot in keyof Slots]: AccountsFor<Slots[Slot]>;
+};
+/** Invocation capabilities every context has, whatever its accounts. */
+export interface InvocationServices {
     /** 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. */
+    /** Text files retained in this version. 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;
-    readonly accounts: {
-        readonly [Slot in keyof Slots]: AccountsFor<Slots[Slot]>;
+}
+/** The app's own accounts, linked for everyone by its managers. Every invocation has them. */
+export interface AppAccountsContext<Slots extends AccountSlots> {
+    readonly app: {
+        readonly accounts: BoundAccounts<Slots>;
+    };
+}
+/** The caller's own linked accounts. App-scope work has no caller, so it has none. */
+export interface UserAccountsContext<Slots extends AccountSlots> {
+    readonly user: {
+        readonly accounts: BoundAccounts<Slots>;
     };
 }
-/** The host evaluates this factory fresh with the configured app's selected accounts. */
-export interface App<Slots extends AccountSlots, Def extends AppDefinition<never>> {
+/**
+ * Current credentials for one invocation. Never retained in source or build output. A context of
+ * the `"app"` scope has no `user`: it serves work without a caller, such as an app schedule.
+ */
+export type BoundContext<Slots extends ScopedSlots, Scope extends AccountScope = "user"> = InvocationServices & AppAccountsContext<Slots["app"]> & ([Scope] extends ["user"] ? UserAccountsContext<Slots["user"]> : unknown);
+/**
+ * What the app factory receives: the app's accounts, and the caller's when the invocation has a
+ * caller. App-scope work evaluates the factory without `user`.
+ */
+export type EvaluationContext<Slots extends ScopedSlots> = BoundContext<Slots, "app"> & Partial<UserAccountsContext<Slots["user"]>>;
+/** The host evaluates this factory fresh with the invocation's accounts. */
+export interface App<Slots extends ScopedSlots, Def extends AppDefinition<never>> {
     readonly accounts: Slots;
-    readonly database?: DatabaseDefinition;
-    readonly evaluate: (context: BoundContext<Slots>) => Effect.Effect<Def, unknown>;
+    /** Declared beside the accounts, so a host lists them without evaluating the app. */
+    readonly events?: Readonly<Record<string, import("./events.js").AppEvent>>;
+    /** Declared beside the accounts and checked when the module loads. */
+    readonly icons?: import("./icons.js").AppIcons;
+    readonly evaluate: (context: EvaluationContext<Slots>) => Effect.Effect<Def, unknown>;
 }
 declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {
     readonly operation: Schema.String;

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. */
@@ -29,11 +35,28 @@ export interface AppCache {
         readonly value: JsonValue;
     }[], retention: Duration.Input) => Promise<void>;
     readonly invalidate: (key: JsonValue) => Promise<void>;
-    /** Uses the current bound credentials' fingerprint, never just the saved account ID. */
+    /**
+     * 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;
 }
+/**
+ * A credential a remote read sends, and the account it belongs to. A public source takes neither.
+ * A credential comes only with its account, so the read is cached in that account's scope.
+ */
+export type AccountCredential<Credential extends object> = ({
+    readonly account?: undefined;
+} & {
+    readonly [Field in keyof Credential]?: undefined;
+}) | ({
+    /** The selected account, as `ctx.app.accounts.<slot>` or `ctx.user.accounts.<slot>` provides it. */
+    readonly account: {
+        readonly id: string;
+    };
+} & Credential);
 /** Trusted storage and background ownership; never accepted from request JSON. */
 export interface HostCache {
     readonly transport: CacheTransport;

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

@@ -1,25 +1,68 @@
 /** Public handler contexts derive capabilities from one shared requirements declaration. */
 import type { WorkflowControls } from "./workflows.js";
-import type { AccountSlots, BoundContext } from "./app.js";
-import type { Database, DatabaseDefinition, DatabaseReader, Tables } from "./storage.js";
-/** Requirements are pure values; selected accounts and database sessions belong to invocations. */
+import type { AccountScope, AccountSlots, BoundContext } from "./app.js";
+import type { Sql, SqlReader } from "./sql.js";
+import type { AnyEventDeclaration, EventEmitter } from "../implementation/events.js";
+import type { AppIcon } from "./icons.js";
+/**
+ * Requirements are pure values; bound accounts and SQL access belong to invocations. `app` names the
+ * accounts the app's managers link for every caller and for background work, `user` the accounts
+ * each caller links. A requirement name is used once across both.
+ */
 export interface AppRequirements {
-    readonly accounts: AccountSlots;
-    readonly database?: DatabaseDefinition;
+    readonly app?: {
+        readonly accounts: AccountSlots;
+    };
+    readonly user?: {
+        readonly accounts: AccountSlots;
+    };
+    /** Removed: declare `user: { accounts }` for the caller's accounts or `app: { accounts }`. */
+    readonly accounts?: never;
+    /** Events this app emits, by name, such as `issue.opened`. */
+    readonly events?: Readonly<Record<string, AnyEventDeclaration>>;
+    /**
+     * Images a dashboard shows for the app, such as its logo in light and dark variants. Each `src`
+     * is base64 `data:image/...` or an `https:` URL; at most 8 icons and 32 KiB in total.
+     */
+    readonly icons?: ReadonlyArray<AppIcon>;
 }
-type StorageContext<Requirements, Writable extends boolean> = Requirements extends {
-    readonly database: DatabaseDefinition<infer T extends Tables>;
-} ? {
-    readonly db: Writable extends true ? Database<T> : DatabaseReader<T>;
-} : {};
-/** Context available during dynamic app evaluation; storage opens only for handlers. */
-export type AppContext<Requirements extends AppRequirements = AppRequirements> = BoundContext<Requirements["accounts"]>;
+/** One scope's requirements; none when the app declares none in it. */
+type ScopeSlots<Requirements, Scope extends AccountScope> = Scope extends keyof Requirements ? NonNullable<Requirements[Scope]> extends {
+    readonly accounts: infer Slots extends AccountSlots;
+} ? Slots : Record<never, never> : Record<never, never>;
+/** An app's requirements by scope, as contexts bind them. */
+export type RequirementSlots<Requirements extends AppRequirements> = {
+    readonly app: ScopeSlots<Requirements, "app">;
+    readonly user: ScopeSlots<Requirements, "user">;
+};
+/** The emitter for an app's declared events. */
+type EventsContext<Requirements extends AppRequirements> = {
+    readonly events: EventEmitter<NonNullable<Requirements["events"]>>;
+};
+/**
+ * Every handler has `ctx.sql`. The app's database exists once the build has SQL files in
+ * `migrations/`; before that, any statement fails and says so.
+ */
+type StorageContext<Writable extends boolean> = {
+    readonly sql: Writable extends true ? Sql : SqlReader;
+};
+/**
+ * Context available during dynamic app evaluation; storage opens only for handlers. `ctx.app.accounts`
+ * holds the app's accounts and `ctx.user.accounts` the caller's. With the `"app"` scope there is no
+ * `user`: app schedules and app-account webhooks run without a caller.
+ */
+export type AppContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = BoundContext<RequirementSlots<Requirements>, Scope>;
 /** Interactive query context; declared storage exposes only read methods. */
-export type QueryContext<Requirements extends AppRequirements = AppRequirements> = AppContext<Requirements> & StorageContext<Requirements, false>;
-/** Interactive mutation context; declared storage belongs to the invocation transaction. */
-export type MutationContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "workflows"> & {
+export type QueryContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = AppContext<Requirements, Scope> & StorageContext<false>;
+/** Interactive mutation context; outside calls happen between SQL transactions, never inside one. */
+export type MutationContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<AppContext<Requirements, Scope>, "workflows"> & {
     readonly workflows: WorkflowControls;
-} & StorageContext<Requirements, true>;
+} & StorageContext<true> & EventsContext<Requirements>;
+/**
+ * The context of a mutation whose handler declares no parameters. It uses no context, so it may run
+ * as the app, such as from an app schedule, where `user` is absent.
+ */
+export type AnyScopeMutationContext<Requirements extends AppRequirements = AppRequirements> = MutationContext<Requirements, "app"> & Partial<Pick<MutationContext<Requirements>, "user">>;
 /** Background webhook context has account and storage access without interactive input. */
-export type WebhookContext<Requirements extends AppRequirements = AppRequirements> = Omit<MutationContext<Requirements>, "elicit">;
+export type WebhookContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<MutationContext<Requirements, Scope>, "elicit">;
 export {};

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

@@ -1,6 +1,6 @@
 /** Shared MCP elicitation data. Delivery belongs to the host, independently of its transport. */
 import { Schema, type Effect } from "effect";
-import * as McpSchema from "effect/unstable/ai/McpSchema";
+import * as McpSchema from "effect/ai/McpSchema";
 import { type JsonValue } from "./schema.js";
 /** Maximum human-input wait, separate from active provider execution time. */
 export declare const ElicitationLimits: Schema.Struct<{
@@ -15,10 +15,10 @@ export declare const defaultElicitationLimits: {
 export declare const FormElicitation: Schema.Struct<{
     readonly mode: Schema.Literal<"form">;
     readonly requestedSchema: Schema.toEncoded<Schema.Struct<{
-        readonly $schema: Schema.decodeTo<Schema.optional<Schema.String>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly $schema: Schema.decodeTo<Schema.toType<Schema.optional<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
         readonly type: Schema.tag<"object">;
         readonly properties: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [typeof McpSchema.LegacyTitledEnum, Schema.Union<readonly [typeof McpSchema.UntitledSingleSelectEnum, typeof McpSchema.TitledSingleSelectEnum]>, Schema.Union<readonly [typeof McpSchema.UntitledMultiSelectEnum, typeof McpSchema.TitledMultiSelectEnum]>]>, typeof McpSchema.ElicitationString, typeof McpSchema.ElicitationNumber, typeof McpSchema.ElicitationBoolean]>>;
-        readonly required: Schema.decodeTo<Schema.optional<Schema.$Array<Schema.String>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+        readonly required: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
     }>>;
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly message: Schema.String;
@@ -28,7 +28,7 @@ export type FormElicitation = typeof FormElicitation.Type;
 export declare const ElicitationResponse: Schema.Union<readonly [Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly action: Schema.Literal<"accept">;
-    readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+    readonly content: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
 }>, Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
@@ -50,7 +50,7 @@ export declare const ElicitationReply: Schema.Union<readonly [Schema.Struct<{
     readonly response: Schema.Union<readonly [Schema.Struct<{
         readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
         readonly action: Schema.Literal<"accept">;
-        readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+        readonly content: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
     }>, Schema.Struct<{
         readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
         readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
@@ -75,12 +75,28 @@ export type ApprovalElicitation = typeof ApprovalElicitation.Type;
 export declare const ApprovalResponse: Schema.Union<readonly [Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly action: Schema.Literal<"accept">;
-    readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+    readonly content: Schema.decodeTo<Schema.toType<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
 }>, Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
     readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
 }>]>;
 export type ApprovalResponse = typeof ApprovalResponse.Type;
-/** Build the framework's own policy prompt after native input decoding. Includes no account credentials. */
+/**
+ * UTF-16 code units of pretty-printed arguments the saved consent prompt shows. Arguments within it
+ * are shown exactly; longer ones are shortened, so a pending request holds the arguments once and
+ * stays small however large the call. The saved call keeps the exact arguments, and surfaces with
+ * room for them show those instead; see `exactApprovalElicitation`.
+ */
+export declare const approvalPreviewChars = 4000;
+/**
+ * The policy prompt with the exact arguments, or undefined when their pretty-printed JSON is longer
+ * than `maxChars` code units. Its work stops at that bound. Includes no account credentials.
+ */
+export declare const exactApprovalElicitation: (toolName: string, input: JsonValue, maxChars: number) => ApprovalElicitation | undefined;
+/**
+ * The policy prompt saved with a pending call: the exact arguments when they fit
+ * `approvalPreviewChars`, otherwise long strings shortened with their length stated. Hosts build it
+ * from the call they saved, so it always describes the exact call approval runs.
+ */
 export declare const approvalElicitation: (toolName: string, input: JsonValue) => ApprovalElicitation;
 export {};