apps 0.0.1-beta.3 → 0.0.1-beta.30

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

@@ -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

@@ -3,7 +3,6 @@ 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 +10,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 +20,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 +43,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;

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

@@ -3,11 +3,15 @@ import { SkillLoadFailed, 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";
@@ -18,15 +22,24 @@ export { ElicitationLimits, defaultElicitationLimits, FormElicitation, Elicitati
 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.
  */
 export { frameworkProtocol } from "./protocol-version.js";
 export { protocol1 } from "./protocols/1.js";
-import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/1.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/1.js";
+export { protocol2 } 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 { AccountCheckResult, AccountInfo } from "./provider.js";
+import { HostAccountsInvalid, HostDeclarationInvalid, HostEvaluationFailed, HostInputInvalid, HostKindMismatch, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, HostRequestInvalid, HostToolApprovalRequired, HostToolBlocked, HostToolNotFound, HostToolPolicyFailed, SkillSources, type InvocationDeadline, ResolvedAccounts, type SkillCatalogResponse, type TrustedToolApproval } from "./protocols/8.js";
+export { DeclaredRequirements, HostRequest } from "./protocols/8.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/8.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. */
@@ -59,6 +72,7 @@ export declare const skillsCommand: (sources: boolean) => {
 export interface SkillCatalog {
     readonly skills: SkillSources["skills"];
     readonly dynamic?: boolean;
+    readonly cached?: boolean;
 }
 export declare const skillCatalog: (response: typeof SkillCatalogResponse.Type) => SkillCatalog;
 /**
@@ -76,16 +90,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, such as a reserved database field, 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<{
@@ -93,5 +115,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/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,31 @@ 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>;
+    }>>;
 }>, 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`.
+ */
 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;

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

@@ -0,0 +1,84 @@
+/**
+ * What app code sees when Executor's app network refuses a request, and the fetch options the
+ * app runtime accepts. A refusal is Executor's decision, not the service's: the request never
+ * left Executor. App code runs on workerd, Cloudflare's runtime, on every host.
+ */
+import { Schema } from "effect";
+/**
+ * Why Executor's app network refused a request.
+ * - `private_address`: the destination is a private, loopback or internal address, and this
+ *   instance lets apps reach only public addresses.
+ * - `credential_host`: the request carries a credential handle, and its provider does not allow
+ *   the destination host.
+ * - `credential_app`: the request carries a credential handle that is not valid for this app.
+ * - `credential_expired`: the request carries an expired credential handle.
+ */
+export declare const NetworkRefusal: Schema.Union<readonly [Schema.Struct<{
+    readonly reason: Schema.Literal<"private_address">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_host">;
+    /** The provider of the credential handle the request carried. */
+    readonly provider: Schema.String;
+    /** The hosts that provider's credentials may reach; empty when it declares none. */
+    readonly allowedHosts: Schema.$Array<Schema.String>;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_app">;
+}>, Schema.Struct<{
+    readonly reason: Schema.Literal<"credential_expired">;
+    /** The provider of the expired credential handle. */
+    readonly provider: Schema.String;
+}>]>;
+export type NetworkRefusal = typeof NetworkRefusal.Type;
+declare const NetworkRefused_base: Schema.Class<NetworkRefused, Schema.TaggedStruct<"NetworkRefused", {
+    /** The refused destination, with its port when the URL names one. */
+    readonly host: Schema.String;
+    readonly refusal: Schema.Union<readonly [Schema.Struct<{
+        readonly reason: Schema.Literal<"private_address">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_host">;
+        /** The provider of the credential handle the request carried. */
+        readonly provider: Schema.String;
+        /** The hosts that provider's credentials may reach; empty when it declares none. */
+        readonly allowedHosts: Schema.$Array<Schema.String>;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_app">;
+    }>, Schema.Struct<{
+        readonly reason: Schema.Literal<"credential_expired">;
+        /** The provider of the expired credential handle. */
+        readonly provider: Schema.String;
+    }>]>;
+}>, import("effect/Cause").YieldableError>;
+/** Executor's app network refused a request before it reached the service. */
+export declare class NetworkRefused extends NetworkRefused_base {
+    get message(): string;
+}
+/**
+ * A refusal reaches app code as a response with this status and header. The header holds the
+ * encoded `NetworkRefused`, so it survives responses without a body, such as to `HEAD`; the
+ * body repeats it as JSON with its message. `ctx.fetch` and the framework's protocol helpers
+ * raise it as `NetworkRefused`; the platform's global `fetch` returns the response. Only
+ * Executor's app network sets the mark: it removes the header from a service's 421 response.
+ */
+export declare const networkRefusalStatus = 421;
+export declare const networkRefusalHeader = "x-executor-refused";
+/** The header's value: the refusal as JSON, URI-encoded so any provider name fits in a header. */
+export declare const NetworkRefusedHeader: Schema.compose<Schema.fromJsonString<typeof NetworkRefused>, Schema.StringFromUriComponent>;
+/** The response Executor's app network returns in place of a request it refused. */
+export declare const networkRefusalResponse: (refused: NetworkRefused) => Response;
+/** RequestInit options the app runtime restricts. */
+export declare const RestrictedFetchOption: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+export type RestrictedFetchOption = typeof RestrictedFetchOption.Type;
+/** The values the app runtime accepts for each restricted option. */
+export declare const supportedFetchOptions: Readonly<Record<RestrictedFetchOption, ReadonlyArray<string>>>;
+declare const FetchOptionUnsupported_base: Schema.Class<FetchOptionUnsupported, Schema.TaggedStruct<"FetchOptionUnsupported", {
+    readonly option: Schema.Literals<readonly ["redirect", "cache", "integrity"]>;
+    readonly value: Schema.String;
+    readonly supported: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** `ctx.fetch` was given a standard RequestInit value the app runtime does not implement. */
+export declare class FetchOptionUnsupported extends FetchOptionUnsupported_base {
+    get message(): string;
+    /** What to do instead, when the standard value has an equivalent the runtime supports. */
+    private get advice();
+}
+export {};

package/types/apps/src/contracts/openapi-compile.d.ts

@@ -1,11 +1,39 @@
 /** Shared OpenAPI compilation diagnostics. */
 import { Schema } from "effect";
-export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+export declare const OpenapiCompileErrorCode: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+/** A declared operation the importer left out, and why. */
+export declare const OpenapiSkippedOperation: Schema.Struct<{
+    /** The tool name the operation would have; reading that tool reports why it is missing. */
+    readonly name: Schema.String;
+    /** The HTTP method, such as `GET`. */
+    readonly method: Schema.String;
+    /** The path as the definition declares it. */
+    readonly path: Schema.String;
+    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly reason: Schema.String;
+}>;
+export type OpenapiSkippedOperation = typeof OpenapiSkippedOperation.Type;
 declare const OpenapiCompileError_base: Schema.Class<OpenapiCompileError, Schema.TaggedStruct<"OpenapiCompileError", {
-    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+    readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
     readonly reason: Schema.String;
+    readonly skipped: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        /** The tool name the operation would have; reading that tool reports why it is missing. */
+        readonly name: Schema.String;
+        /** The HTTP method, such as `GET`. */
+        readonly method: Schema.String;
+        /** The path as the definition declares it. */
+        readonly path: Schema.String;
+        readonly code: Schema.Literals<readonly ["server_protocol", "server_url", "external_reference", "circular_reference", "schema_keyword", "schema_reference", "missing_component", "openapi_version", "auth_helper", "auth_missing", "operation_path", "operation_method", "duplicate_operation", "server_missing", "multiple_hosts", "parameter_encoding", "parameter_style", "request_body", "combined_oauth", "auth_method", "event_stream", "input_schema", "no_operations", "no_supported_operations", "invalid_document", "source_generation", "authoring_reference"]>;
+        readonly reason: Schema.String;
+    }>>>;
+    readonly origins: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
-/** A safe generation failure, translated into product HTTP errors at the boundary. */
+/**
+ * A safe generation failure. `reason` explains the cause; `skipped` lists the declared operations
+ * it left out and why, and `origins` the origins operations resolve to when none of them matches
+ * the allowed origin. Reading one left-out tool fails with this error for that operation alone.
+ */
 export declare class OpenapiCompileError extends OpenapiCompileError_base {
+    get message(): string;
 }
 export {};