apps 0.0.1-beta.4 → 0.0.1-beta.41

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,8 +19,6 @@ 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 config: Schema.Decoder<unknown>;
@@ -46,7 +42,11 @@ export interface BoundContext<Slots extends AccountSlots> {
     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;
@@ -57,7 +57,6 @@ export interface BoundContext<Slots extends AccountSlots> {
 /** The host evaluates this factory fresh with the configured app's selected accounts. */
 export interface App<Slots extends AccountSlots, Def extends AppDefinition<never>> {
     readonly accounts: Slots;
-    readonly database?: DatabaseDefinition;
     readonly evaluate: (context: BoundContext<Slots>) => Effect.Effect<Def, unknown>;
 }
 declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {

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

@@ -37,6 +37,20 @@ export interface AppCache {
         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 `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,26 @@
 /** 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 { Sql, SqlReader } from "./sql.js";
+/** Requirements are pure values; selected accounts and SQL access belong to invocations. */
 export interface AppRequirements {
     readonly accounts: AccountSlots;
-    readonly database?: DatabaseDefinition;
 }
-type StorageContext<Requirements, Writable extends boolean> = Requirements extends {
-    readonly database: DatabaseDefinition<infer T extends Tables>;
-} ? {
-    readonly db: Writable extends true ? Database<T> : DatabaseReader<T>;
-} : {};
+/**
+ * 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. */
 export type AppContext<Requirements extends AppRequirements = AppRequirements> = BoundContext<Requirements["accounts"]>;
 /** 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 QueryContext<Requirements extends AppRequirements = AppRequirements> = AppContext<Requirements> & StorageContext<false>;
+/** Interactive mutation context; outside calls happen between SQL transactions, never inside one. */
 export type MutationContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "workflows"> & {
     readonly workflows: WorkflowControls;
-} & StorageContext<Requirements, true>;
+} & StorageContext<true>;
 /** Background webhook context has account and storage access without interactive input. */
 export type WebhookContext<Requirements extends AppRequirements = AppRequirements> = Omit<MutationContext<Requirements>, "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,7 +75,7 @@ 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"]>;

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

@@ -0,0 +1,54 @@
+/** 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, or the thrown error's own `code`. */
+export declare const FailureCode: Schema.String;
+/** Bounded, with the invocation's account secrets replaced. */
+export declare const FailureMessage: Schema.String;
+/** Most fields of one thrown error carried across the runtime boundary. */
+export declare const maxFailureFields = 8;
+/** Longest text field value carried across the runtime boundary. */
+export declare const maxFailureFieldLength = 256;
+/** A field name as the error's code spells it, such as `reason` or `pointer`. */
+export declare const FailureFieldName: Schema.String;
+/** Bounded text with account secrets replaced, a finite number, or a boolean. */
+export declare const FailureFieldValue: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+/**
+ * The thrown error's own scalar fields beside its name, code and message, such as the `reason`
+ * and `pointer` a spec compiler sets. Nested values, stacks and causes are never carried.
+ */
+export declare const FailureFields: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+export type FailureFields = typeof FailureFields.Type;
+/**
+ * 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>;
+    fields: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+};
+/** Longest error message a service stated, as carried across the runtime boundary. */
+export declare const maxUpstreamMessageLength = 1024;
+/**
+ * The error a service stated in its own response: a JSON-RPC error's code and message, or an
+ * OAuth Bearer error code and description. Bounded, with the invocation's account secrets replaced.
+ */
+export declare const UpstreamError: Schema.Struct<{
+    readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>;
+export type UpstreamError = typeof UpstreamError.Type;
+/** Where a service failed: setting up a session, listing tools, or running one. */
+export declare const FailurePhase: Schema.Literals<readonly ["connect", "discover", "call"]>;
+export type FailurePhase = typeof FailurePhase.Type;

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

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** GraphQL discovery contracts. Catalogs are evaluated with the selected account. */
 import { Schema, type Effect } from "effect";
 import { type JsonValue } from "./schema.js";
@@ -97,7 +98,7 @@ export interface GraphqlTool {
     readonly description: string;
     readonly readOnly: boolean;
     readonly input: Schema.Decoder<JsonValue>;
-    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError>;
+    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError | NetworkRefused>;
 }
 /** One tool per root field; subscriptions require a separate long-lived host. */
 export type GraphqlTools = Readonly<Record<string, GraphqlTool>>;

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

@@ -1,24 +1,26 @@
 export * from "./skills.js";
-import { SkillLoadFailed, type SkillFile } from "./skills.js";
+import { type SkillFile } from "./skills.js";
 import { ProviderError } from "./provider-error.js";
-import { McpError } from "./mcp.js";
 import { OpenapiResponseError } from "./api-response-error.js";
-export { ApiErrorResponse, OpenapiResponseError } from "./api-response-error.js";
+export { ApiErrorResponse, maxApiErrorInstructionsLength, maxApiErrorMessageLength, OpenapiResponseError, } from "./api-response-error.js";
 export { ProviderError } from "./provider-error.js";
-export { McpError } from "./mcp.js";
+export { FetchOptionUnsupported, NetworkRefusal, NetworkRefused, networkRefusalHeader, networkRefusalResponse, networkRefusalStatus, } from "./network.js";
 import { WorkflowFailure, type WorkflowExecution, type WorkflowReplay, type WorkflowHostControls } from "./workflows.js";
 export * from "./workflows.js";
+export * from "./failure.js";
+import { DatabaseFieldReserved, DatabaseLimitExceeded } from "../../../app-data/src/contracts/database.js";
+export { DatabaseFieldReserved, DatabaseLimitExceeded } from "../../../app-data/src/contracts/database.js";
 /** Portable framework dispatch contracts. Requests never carry account bindings. */
 import { Context, Schema, type Effect, type Redacted } from "effect";
-import type { AppStorage } from "./storage.js";
+import type { AppSqlStorage } from "./sql.js";
 import type { InvocationTelemetry } from "../../../telemetry/src/index.js";
-export { AppStorageError, AppStorageUnavailable, StorageName, type AppStorage } from "./storage.js";
+export { type AppSqlStorage, type Sql, type SqlCursor, type SqlReader, type SqlRow, type SqlValue, } from "./sql.js";
 import { ElicitationFailed, type ElicitationHandler } from "./elicitation.js";
 export { ElicitationLimits, defaultElicitationLimits, FormElicitation, ElicitationResponse, ElicitationReply, ElicitationFailed, type ElicitationHandler, ApprovalElicitation, ApprovalResponse, approvalElicitation, } from "./elicitation.js";
 export { McpClientLimits, defaultMcpClientLimits } from "./mcp.js";
 export * from "./webhook-protocol.js";
 export { AccountId, HttpUrl } from "./schema.js";
-export { OAuthClientAuth, OAuthSecretClientAuth } from "./provider.js";
+export { OAuthClientAuth, OAuthSecretClientAuth, OAuthTokenRequestFormat, OAuthTokenResponse, } from "./provider.js";
 /**
  * The host protocol this framework speaks and its wire schemas. A later protocol replaces this
  * re-export; released protocol modules stay unchanged for host adapters.
@@ -26,8 +28,23 @@ export { OAuthClientAuth, OAuthSecretClientAuth } from "./provider.js";
 export { frameworkProtocol } from "./protocol-version.js";
 export { protocol1 } from "./protocols/1.js";
 export { protocol2 } from "./protocols/2.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/2.js";
-export { DeclaredAuthMethod, DeclaredProvider, DeclaredRequirements, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, SkillSources, SkillCatalogResponse, HostRequest, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/2.js";
+export { protocol3 } from "./protocols/3.js";
+export { protocol4 } from "./protocols/4.js";
+export { protocol5 } from "./protocols/5.js";
+export { protocol6 } from "./protocols/6.js";
+export { protocol7, AccountCheckCommand, CredentialHost } from "./protocols/7.js";
+export { protocol8 } from "./protocols/8.js";
+export { protocol9 } from "./protocols/9.js";
+export { protocol10, MigrateCommand, MigrateResult } from "./protocols/10.js";
+export { AccountCheckResult, AccountInfo } from "./provider.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, McpError, SkillLoadFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/10.js";
+export { DeclaredRequirements, HostRequest } from "./protocols/10.js";
+/**
+ * The MCP and skill loader failures as they cross the host boundary. Apps throw the author-facing
+ * classes from `apps/mcp` and `apps/skills`.
+ */
+export { McpError, SkillLoadFailed } from "./protocols/10.js";
+export { DeclaredAuthMethod, DeclaredProvider, ResolvedAccount, ResolvedAccounts, TrustedToolApproval, InvocationDeadline, HostedTool, HostedToolSummary, HostRouterError, HostedRouter, HostedCatalog, HostedCatalogSummary, SkillSources, SkillCatalogResponse, HostRequestInvalid, HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostOperationNotFound, HostOperationFailed, HostToolNotFound, HostKindMismatch, InputProblem, maxInputProblems, HostInputInvalid, HostToolBlocked, HostToolApprovalRequired, HostToolPolicyFailed, HostOutputInvalid, HostError, HostResponse, HostInvocation, } from "./protocols/10.js";
 /** Raw host inputs; the host boundary parses and redacts these immediately. */
 export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
 /** Trusted invocation context, supplied separately from the Request. */
@@ -46,7 +63,8 @@ export interface HostContext {
     /** Trusted in-process tracing capability; never decoded from a public request. */
     readonly telemetry?: InvocationTelemetry;
     readonly approval?: TrustedToolApproval;
-    readonly storage?: AppStorage;
+    /** The data facet's SQLite storage, for apps that declare `sql`. Never exposed to app code. */
+    readonly storage?: AppSqlStorage;
     readonly accounts: Redacted.Redacted<ResolvedAccounts>;
 }
 /** Skill commands. Send sources only to builds that declare skillSources. */
@@ -78,16 +96,24 @@ export declare const indexCommand: {
 };
 /** Keep only the requested tools from an inspection that may have described every tool. */
 export declare const selectTools: (tools?: readonly string[]) => <A extends {
-    readonly name: string;
-}>(all: readonly A[]) => readonly A[];
-/** Declaration reads do not bind accounts or evaluate the app factory. */
-export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid]>;
+    readonly tools: readonly {
+        readonly name: string;
+    }[];
+}>(catalog: A) => A;
+/** Declaration reads do not bind accounts or evaluate the app factory. A named declaration
+ * problem is reported so the deploy can explain it. */
+export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof DatabaseFieldReserved]>;
 /** Inspection can fail while binding accounts or evaluating the live definition. */
 export declare const HostInspectError: Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>;
 /** Tool invocation adds lookup, input, execution and output failures to inspection. */
-export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostCallError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostKindMismatch, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+/**
+ * An account check binds one account and runs the provider's check without evaluating the app.
+ * Timeouts arrive as WorkflowFailure from the shared deadline guard.
+ */
+export declare const HostAccountCheckError: Schema.Union<readonly [typeof ProviderError, typeof WorkflowFailure, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostOutputInvalid]>;
 /** Queries, mutations and agent calls use the same operation failures. */
-export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+export declare const HostDataError: Schema.Union<readonly [typeof OpenapiResponseError, typeof WorkflowFailure, Schema.Union<readonly [typeof ProviderError, typeof McpError, typeof SkillLoadFailed, typeof HostRequestInvalid, typeof HostDeclarationInvalid, typeof HostAccountsInvalid, typeof HostEvaluationFailed]>, typeof HostToolNotFound, typeof HostOperationNotFound, typeof HostKindMismatch, typeof HostOperationFailed, typeof DatabaseLimitExceeded, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
 /** Invocation-owned outcome sink. Framework adapters report semantic failures
  * independently of successful JSON transport; customer output is never inspected. */
 export declare const ToolResultObservation: Context.Reference<{
@@ -95,5 +121,6 @@ export declare const ToolResultObservation: Context.Reference<{
 }>;
 /** Native handler; context comes from host authority, never from request content. */
 export type AppHandler = (request: Request, context: HostContext) => Effect.Effect<Response>;
-export { OperationToolPrefixes, type AppOperation, type OperationContext } from "./operations.js";
+export { type AppOperation, type OperationContext } from "./operations.js";
+export { RouterIcon, RouterKey, RouterMeta, type AppNode, type AppRouter, type DynamicRouter, } from "./router.js";
 export * from "./schedules.js";

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

@@ -1,6 +1,8 @@
 /** Browser subscription contracts contain no executable server declarations. */
 import { Schema } from "effect";
 import type { JsonValue } from "./schema.js";
+/** Names of authored operations. */
+export declare const OperationName: Schema.NonEmptyString;
 /** Serializable named reference; the phantom field is never populated at runtime. */
 export interface OperationReference<Input, Output, Kind extends "query" | "mutation"> {
     readonly name: string;

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

@@ -1,7 +1,9 @@
-import type { ProviderError } from "./provider-error.js";
+import { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** MCP protocol data uses Effect Schema; executable tool methods use Effect. */
 import { type Effect, type Redacted, Schema } from "effect";
 import type { Elicit, ElicitationFailed } from "./elicitation.js";
+import type { AccountCheckContext, AuthMethods } from "./provider.js";
 import { type JsonValue } from "./schema.js";
 /** Upstream MCP resource bounds, independent of the outer codemode execution budget. */
 export declare const McpClientLimits: Schema.Struct<{
@@ -31,6 +33,37 @@ export declare const McpToolsOptions: Schema.Struct<{
     readonly timeoutMs: Schema.optional<Schema.Number>;
 }>;
 export type McpToolsOptions = typeof McpToolsOptions.Type;
+/**
+ * What `mcpHealth` checks, as decoded: its options, with the account's ID, signal and deadline
+ * taken from the check context.
+ */
+export declare const McpHealthInput: Schema.Struct<{
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly deadline: Schema.optional<Schema.Finite>;
+    readonly url: Schema.String;
+    readonly accountId: Schema.optional<Schema.brand<Schema.String, "acc">>;
+    readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>;
+/**
+ * The server a provider check verifies, and the headers that send the checked account's
+ * credentials. The account, signal and deadline come from the check context instead. Both attempts
+ * share one budget that ends `mcpHealthReserveMs` before the deadline. `timeoutMs` bounds the whole
+ * check too; it can shorten the budget, never extend it.
+ */
+export type McpHealthOptions = Pick<typeof McpHealthInput.Type, "url" | "headers" | "timeoutMs">;
+/** What `mcpHealth` reads from the check context the host passes to a provider's `health`. */
+export type McpHealthCheck = Pick<AccountCheckContext<AuthMethods>, "signal" | "deadline"> & {
+    readonly account: {
+        readonly id: string;
+    };
+};
+/**
+ * How long before an account check's deadline `mcpHealth` stops waiting for the server, so it can
+ * still close its session, ending it and then its transport, each within `cleanupTimeoutMs`, and
+ * report why before the host stops waiting.
+ */
+export declare const mcpHealthReserveMs: number;
 /** One parsed server and credential snapshot; never shared across account evaluations. */
 export interface McpConnection {
     readonly url: URL;
@@ -38,15 +71,21 @@ export interface McpConnection {
     readonly timeoutMs: number;
 }
 export { ToolAnnotations as McpToolAnnotations } from "./tools.js";
-/** Native MCP result semantics. Protocol/transport failures use the Effect error channel. */
+/**
+ * Native MCP result semantics, and the value every MCP tool call returns. A tool's output
+ * schema is built from this declaration. Protocol/transport failures use the Effect error channel.
+ */
 export declare const McpToolResult: Schema.Struct<{
     readonly content: Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly structuredContent: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
-    readonly isError: Schema.optional<Schema.Boolean>;
-    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly structuredContent: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly isError: Schema.optionalKey<Schema.Boolean>;
+    readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolResult = typeof McpToolResult.Type;
-/** Remote metadata. Input/output schemas remain upstream JSON Schema documents. */
+/**
+ * Remote metadata. Input/output schemas remain upstream JSON Schema documents; the upstream
+ * output schema describes only a result's `structuredContent`.
+ */
 export declare const McpToolMetadata: Schema.Struct<{
     readonly name: Schema.String;
     readonly title: Schema.optional<Schema.String>;
@@ -63,16 +102,37 @@ export declare const McpToolMetadata: Schema.Struct<{
     readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type McpToolMetadata = typeof McpToolMetadata.Type;
+/** What a server reports about itself when a session initializes. Icons are for display only. */
+export declare const McpServerHeader: Schema.Struct<{
+    readonly name: Schema.optionalKey<Schema.String>;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly version: Schema.optionalKey<Schema.String>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly websiteUrl: Schema.optionalKey<Schema.String>;
+    readonly icons: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly src: Schema.NonEmptyString;
+        readonly mimeType: Schema.optionalKey<Schema.String>;
+        readonly sizes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly theme: Schema.optionalKey<Schema.Literals<readonly ["light", "dark"]>>;
+    }>>>;
+    readonly instructions: Schema.optionalKey<Schema.String>;
+}>;
+export type McpServerHeader = typeof McpServerHeader.Type;
 /** Direct callers can omit interaction capabilities. A server that asks for input then fails explicitly. */
 export interface McpToolContext {
     readonly elicit?: Elicit;
 }
-/** A tool bound to one evaluation's account; do not reuse it with another account. */
-export interface McpTool extends McpToolMetadata {
+/**
+ * A tool bound to one evaluation's account; do not reuse it with another account. `output`
+ * decodes and describes the `McpToolResult` that `run` returns, with the upstream output schema
+ * under `structuredContent`.
+ */
+export interface McpTool extends Omit<McpToolMetadata, "outputSchema"> {
     readonly description: string;
     readonly input: Schema.Decoder<JsonValue>;
+    readonly output: Schema.Decoder<JsonValue>;
     readonly readOnly?: boolean;
-    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | ElicitationFailed>;
+    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ProviderError | NetworkRefused | ElicitationFailed>;
 }
 /** The discovered catalog keyed by remote tool name. */
 export type McpTools = Readonly<Record<string, McpTool>>;
@@ -80,10 +140,36 @@ declare const McpError_base: Schema.Class<McpError, Schema.TaggedStruct<"McpErro
     readonly phase: Schema.Literals<readonly ["connect", "discover", "call", "schema", "transport"]>;
     readonly reason: Schema.Literals<readonly ["request", "unauthorized", "invalid_response", "timeout", "invalid_input"]>;
     readonly status: Schema.optional<Schema.Number>;
+    readonly upstream: Schema.optional<Schema.Struct<{
+        readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+        readonly message: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly session: Schema.optional<Schema.Literal<true>>;
 }>, import("effect/Cause").YieldableError>;
-/** Safe protocol/transport failure; no raw upstream payloads or credentials. */
+/**
+ * Safe protocol/transport failure; no raw upstream payloads or credentials. `status` is the HTTP
+ * status a `request` failure was redirected or refused with. Without one, a `request` failure in
+ * the `transport` phase never reached the server; in another phase it may be a JSON-RPC error the
+ * server answered with. `upstream` is that JSON-RPC error, bounded and with account secrets
+ * replaced. A response that is not MCP is `invalid_response`. `session` is set when the refused
+ * request carried the session ID the server issued at initialization.
+ *
+ * These fields describe the failure for whoever reads it. App code can set any of them, so they
+ * never show that the failure lies outside Executor.
+ */
 export declare class McpError extends McpError_base {
 }
+declare const McpCredentialsUnverified_base: Schema.Class<McpCredentialsUnverified, Schema.TaggedStruct<"McpCredentialsUnverified", {
+    readonly anonymous: Schema.Union<readonly [Schema.Literal<"answered">, typeof McpError, typeof ProviderError]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `mcpHealth` could not show that the server needs the account's credentials, although it accepted
+ * them. `anonymous` is what the same check without credentials met: `answered` when it succeeded,
+ * so a refused key would pass too, or the failure, other than a refusal, that left it undecided.
+ * Only app code raises it; the host reports its fixed message, so no host protocol carries it.
+ */
+export declare class McpCredentialsUnverified extends McpCredentialsUnverified_base {
+}
 /** Public process configuration. Credentials arrive through the selected account. */
 export declare const ProcessConfig: Schema.Struct<{
     readonly command: Schema.NonEmptyString;