apps 0.0.1-beta.0

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

@@ -0,0 +1,568 @@
+import { WorkflowFailure, type WorkflowExecution, type WorkflowReplay, type WorkflowHostControls } from "./workflows.js";
+export * from "./workflows.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 { InvocationTelemetry } from "../../../telemetry/src/index.js";
+export { AppStorageError, AppStorageUnavailable, StorageName, type AppStorage } from "./storage.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";
+/** Serializable auth methods shared with SDK hosts; protocol configuration has one schema. */
+export declare const DeclaredAuthMethod: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"secrets">;
+    readonly label: Schema.String;
+    readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+    readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly type: Schema.Literal<"oauth2">;
+}>, Schema.Struct<{
+    readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly scopes: Schema.$Array<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly type: Schema.Literal<"oauth2">;
+}>, Schema.Struct<{
+    readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly type: Schema.Literal<"oauth2">;
+}>, Schema.Struct<{
+    readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly scopes: Schema.$Array<Schema.String>;
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly type: Schema.Literal<"oauth2">;
+}>]>;
+/** Serializable declaration of a provider's named authentication methods. */
+export declare const DeclaredProvider: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly auth: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"secrets">;
+        readonly label: Schema.String;
+        readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>, Schema.Struct<{
+        readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly discover: Schema.String;
+        readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+        readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+        readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+        readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+        readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly type: Schema.Literal<"oauth2">;
+    }>, Schema.Struct<{
+        readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly authorizationUrl: Schema.String;
+        readonly tokenUrl: Schema.String;
+        readonly scopes: Schema.$Array<Schema.String>;
+        readonly discover: Schema.optionalKey<Schema.Never>;
+        readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+        readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+        readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly type: Schema.Literal<"oauth2">;
+    }>, Schema.Struct<{
+        readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly grant: Schema.Literal<"client_credentials">;
+        readonly discover: Schema.String;
+        readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+        readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+        readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+        readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly type: Schema.Literal<"oauth2">;
+    }>, Schema.Struct<{
+        readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly grant: Schema.Literal<"client_credentials">;
+        readonly tokenUrl: Schema.String;
+        readonly scopes: Schema.$Array<Schema.String>;
+        readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+        readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+        readonly discover: Schema.optionalKey<Schema.Never>;
+        readonly type: Schema.Literal<"oauth2">;
+    }>]>>;
+}>;
+/** Credential-free provider declaration; content matching remains host policy. */
+export type DeclaredProvider = typeof DeclaredProvider.Type;
+/** Account slots available without binding accounts or evaluating the app factory. */
+export declare const DeclaredRequirements: Schema.Struct<{
+    readonly database: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly fields: Schema.$Record<Schema.String, Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+            readonly optional: Schema.optional<Schema.Boolean>;
+            readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+            readonly references: Schema.optional<Schema.String>;
+        }>>;
+        readonly indexes: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly fields: Schema.NonEmptyArray<Schema.String>;
+        }>>;
+    }>>>;
+    readonly accounts: Schema.$Record<Schema.NonEmptyString, Schema.Struct<{
+        readonly definition: Schema.Struct<{
+            readonly name: Schema.NonEmptyString;
+            readonly auth: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Literal<"secrets">;
+                readonly label: Schema.String;
+                readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            }>, Schema.Struct<{
+                readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly discover: Schema.String;
+                readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+                readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+                readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+                readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+                readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+                readonly type: Schema.Literal<"oauth2">;
+            }>, Schema.Struct<{
+                readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly authorizationUrl: Schema.String;
+                readonly tokenUrl: Schema.String;
+                readonly scopes: Schema.$Array<Schema.String>;
+                readonly discover: Schema.optionalKey<Schema.Never>;
+                readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+                readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+                readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+                readonly type: Schema.Literal<"oauth2">;
+            }>, Schema.Struct<{
+                readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly grant: Schema.Literal<"client_credentials">;
+                readonly discover: Schema.String;
+                readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+                readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+                readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+                readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+                readonly type: Schema.Literal<"oauth2">;
+            }>, Schema.Struct<{
+                readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly grant: Schema.Literal<"client_credentials">;
+                readonly tokenUrl: Schema.String;
+                readonly scopes: Schema.$Array<Schema.String>;
+                readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+                readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+                readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+                readonly discover: Schema.optionalKey<Schema.Never>;
+                readonly type: Schema.Literal<"oauth2">;
+            }>]>>;
+        }>;
+        readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
+    }>>;
+}>;
+/** Parsed declared account requirements. */
+export type DeclaredRequirements = typeof DeclaredRequirements.Type;
+/** Host-resolved credentials for one stable saved account. Never a request DTO. */
+export declare const ResolvedAccount: Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "acc">;
+    readonly provider: Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly auth: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"secrets">;
+            readonly label: Schema.String;
+            readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly authorizationUrl: Schema.String;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>]>>;
+    }>;
+    readonly method: Schema.NonEmptyString;
+    readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Parsed host account binding. */
+export type ResolvedAccount = typeof ResolvedAccount.Type;
+/** Full saved selection resolved by the trusted caller; [] differs from a missing slot. */
+export declare const ResolvedAccounts: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "acc">;
+    readonly provider: Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly auth: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"secrets">;
+            readonly label: Schema.String;
+            readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly authorizationUrl: Schema.String;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>]>>;
+    }>;
+    readonly method: Schema.NonEmptyString;
+    readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.$Array<Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "acc">;
+    readonly provider: Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly auth: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"secrets">;
+            readonly label: Schema.String;
+            readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly authorizationUrl: Schema.String;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+            readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly discover: Schema.String;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+            readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>, Schema.Struct<{
+            readonly response: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly grant: Schema.Literal<"client_credentials">;
+            readonly tokenUrl: Schema.String;
+            readonly scopes: Schema.$Array<Schema.String>;
+            readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+            readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+            readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+            readonly discover: Schema.optionalKey<Schema.Never>;
+            readonly type: Schema.Literal<"oauth2">;
+        }>]>>;
+    }>;
+    readonly method: Schema.NonEmptyString;
+    readonly fields: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>>]>>;
+/** Raw host inputs; the host boundary parses and redacts these immediately. */
+export type ResolvedAccountsInput = typeof ResolvedAccounts.Encoded;
+/** Parsed host selections, kept redacted until native account binding. */
+export type ResolvedAccounts = typeof ResolvedAccounts.Type;
+/** Trusted approval for one decoded call. Never accepted in public command JSON. */
+export declare const TrustedToolApproval: Schema.Struct<{
+    readonly tool: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+export type TrustedToolApproval = typeof TrustedToolApproval.Type;
+/** Trusted invocation context, supplied separately from the Request. */
+export interface HostContext {
+    /** Private delivery capability. It is never accepted in public request JSON or stored in a build. */
+    readonly workflowControls?: WorkflowHostControls;
+    readonly workflow?: WorkflowExecution;
+    readonly replay?: WorkflowReplay;
+    readonly elicitation?: ElicitationHandler;
+    /** Trusted in-process tracing capability; never decoded from a public request. */
+    readonly telemetry?: InvocationTelemetry;
+    readonly approval?: TrustedToolApproval;
+    readonly storage?: AppStorage;
+    readonly accounts: Redacted.Redacted<ResolvedAccounts>;
+}
+/** Serializable live tool metadata; executable callbacks never cross this boundary. */
+export declare const HostedTool: Schema.Struct<{
+    readonly schedules: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly timing: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"interval">;
+            readonly milliseconds: Schema.Int;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"cron">;
+            readonly calendar: Schema.Struct<{
+                readonly expression: Schema.NonEmptyString;
+                readonly timezone: Schema.NonEmptyString;
+            }>;
+        }>]>;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>>;
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly readOnly: Schema.optionalKey<Schema.Boolean>;
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly annotations: Schema.optionalKey<Schema.Struct<{
+        readonly title: Schema.optionalKey<Schema.String>;
+        readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+        readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+        readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+        readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+    }>>;
+    readonly _meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+/** Parsed live tool description. */
+export type HostedTool = typeof HostedTool.Type;
+/** Framework-owned dispatch, independent of app-authored HTTP routing. */
+export declare const HostRequest: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"workflows">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"workflow-validate">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"workflow-run">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>]>, Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"webhooks">;
+}>, Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-validate">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-complete">;
+}>, Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-register">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-unregister">;
+}>, Schema.Struct<{
+    readonly state: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly request: Schema.Struct<{
+        readonly url: Schema.String;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+        readonly headers: Schema.$Record<Schema.String, Schema.String>;
+        readonly body: Schema.String;
+    }>;
+    readonly name: Schema.NonEmptyString;
+    readonly subscriptionId: Schema.NonEmptyString;
+    readonly sourceAccount: Schema.brand<Schema.String, "acc">;
+    readonly callbackUrl: Schema.String;
+    readonly secret: Schema.String;
+    readonly config: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly operation: Schema.Literal<"webhook-handle">;
+}>]>, Schema.Struct<{
+    readonly operation: Schema.Literal<"requirements">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"inspect">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"query">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"mutate">;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"call">;
+    readonly tool: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>]>;
+/** Parsed portable dispatch request. */
+export type HostRequest = typeof HostRequest.Type;
+declare const HostRequestInvalid_base: Schema.Class<HostRequestInvalid, Schema.TaggedStruct<"HostRequestInvalid", {}>, import("effect/Cause").YieldableError>;
+/** The dispatch request did not match the protocol. */
+export declare class HostRequestInvalid extends HostRequestInvalid_base {
+}
+declare const HostAccountsInvalid_base: Schema.Class<HostAccountsInvalid, Schema.TaggedStruct<"HostAccountsInvalid", {}>, import("effect/Cause").YieldableError>;
+/** Host-supplied accounts did not satisfy the declared slots or native method schemas. */
+export declare class HostAccountsInvalid extends HostAccountsInvalid_base {
+}
+declare const HostDeclarationInvalid_base: Schema.Class<HostDeclarationInvalid, Schema.TaggedStruct<"HostDeclarationInvalid", {}>, import("effect/Cause").YieldableError>;
+/** The module or declared capability shape could not be hosted. */
+export declare class HostDeclarationInvalid extends HostDeclarationInvalid_base {
+}
+declare const HostEvaluationFailed_base: Schema.Class<HostEvaluationFailed, Schema.TaggedStruct<"HostEvaluationFailed", {}>, import("effect/Cause").YieldableError>;
+/** Fresh app evaluation failed before calling a tool. */
+export declare class HostEvaluationFailed extends HostEvaluationFailed_base {
+}
+declare const HostOperationNotFound_base: Schema.Class<HostOperationNotFound, Schema.TaggedStruct<"HostOperationNotFound", {}>, import("effect/Cause").YieldableError>;
+/** No query or mutation matched the requested name. */
+export declare class HostOperationNotFound extends HostOperationNotFound_base {
+}
+declare const HostOperationFailed_base: Schema.Class<HostOperationFailed, Schema.TaggedStruct<"HostOperationFailed", {}>, import("effect/Cause").YieldableError>;
+/** An app operation failed. Raw author failures remain private. */
+export declare class HostOperationFailed extends HostOperationFailed_base {
+}
+declare const HostToolNotFound_base: Schema.Class<HostToolNotFound, Schema.TaggedStruct<"HostToolNotFound", {}>, import("effect/Cause").YieldableError>;
+/** The freshly evaluated catalog did not contain the requested tool. */
+export declare class HostToolNotFound extends HostToolNotFound_base {
+}
+declare const HostInputInvalid_base: Schema.Class<HostInputInvalid, Schema.TaggedStruct<"HostInputInvalid", {}>, import("effect/Cause").YieldableError>;
+/** Native input decoding failed; supplied values are omitted. */
+export declare class HostInputInvalid extends HostInputInvalid_base {
+}
+declare const HostToolBlocked_base: Schema.Class<HostToolBlocked, Schema.TaggedStruct<"HostToolBlocked", {}>, import("effect/Cause").YieldableError>;
+/** The tool's approval policy blocked this call before its tool body ran. */
+export declare class HostToolBlocked extends HostToolBlocked_base {
+}
+declare const HostToolApprovalRequired_base: Schema.Class<HostToolApprovalRequired, Schema.TaggedStruct<"HostToolApprovalRequired", {
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly elicitation: Schema.Struct<{
+        readonly requestedSchema: Schema.Struct<{
+            readonly type: Schema.Literal<"object">;
+            readonly properties: Schema.$Record<Schema.String, Schema.Never>;
+        }>;
+        readonly mode: Schema.Literal<"form">;
+        readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly message: Schema.String;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+/** Policy elicitation plus decoded input. No tool body ran; the host owns delivery and resumption. */
+export declare class HostToolApprovalRequired extends HostToolApprovalRequired_base {
+}
+declare const HostToolPolicyFailed_base: Schema.Class<HostToolPolicyFailed, Schema.TaggedStruct<"HostToolPolicyFailed", {}>, import("effect/Cause").YieldableError>;
+/** The tool's approval policy failed or returned an invalid decision. Author failures remain private. */
+export declare class HostToolPolicyFailed extends HostToolPolicyFailed_base {
+}
+declare const HostOutputInvalid_base: Schema.Class<HostOutputInvalid, Schema.TaggedStruct<"HostOutputInvalid", {}>, import("effect/Cause").YieldableError>;
+/** A tool result was not JSON; the result is never included in the error. */
+export declare class HostOutputInvalid extends HostOutputInvalid_base {
+}
+/** Declaration reads do not bind accounts or evaluate the app factory. */
+export declare const HostRequirementsError: Schema.Union<readonly [typeof HostRequestInvalid, typeof HostDeclarationInvalid]>;
+/** Inspection can fail while binding accounts or evaluating the live definition. */
+export declare const HostInspectError: Schema.Union<readonly [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 WorkflowFailure, Schema.Union<readonly [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]>;
+/** Queries, mutations and agent calls use the same operation failures. */
+export declare const HostDataError: Schema.Union<readonly [typeof WorkflowFailure, Schema.Union<readonly [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]>;
+/** Safe error envelope; no author exception, source, account fields or stack is serialized. */
+export declare const HostError: Schema.Union<readonly [typeof WorkflowFailure, typeof HostRequestInvalid, typeof HostAccountsInvalid, typeof HostDeclarationInvalid, typeof HostEvaluationFailed, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostToolNotFound, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+/** Expected host failures. */
+export type HostError = typeof HostError.Type;
+/** 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<{
+    readonly failed: () => void;
+}>;
+/** Portable response envelope; callers parse the success value for their operation. */
+export declare const HostResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly toolError: Schema.optionalKey<Schema.Literal<true>>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: Schema.Union<readonly [typeof WorkflowFailure, typeof HostRequestInvalid, typeof HostAccountsInvalid, typeof HostDeclarationInvalid, typeof HostEvaluationFailed, typeof HostOperationNotFound, typeof HostOperationFailed, typeof HostToolNotFound, typeof HostInputInvalid, typeof HostOutputInvalid, typeof HostToolBlocked, typeof HostToolApprovalRequired, typeof HostToolPolicyFailed, typeof ElicitationFailed]>;
+}>]>;
+/** Parsed response envelope. */
+export type HostResponse = typeof HostResponse.Type;
+/** 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 * from "./schedules.js";

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

@@ -0,0 +1,20 @@
+/** Native HTTP decoding contract. The public boundary adapts fetch Responses. */
+import { type Effect, Schema } from "effect";
+/** The response capability needed by the decoder, already adapted into Effect. */
+export interface JsonResponse {
+    readonly status: number;
+    readonly json: () => Effect.Effect<unknown, ResponseDecodeError>;
+}
+declare const ResponseStatusError_base: Schema.Class<ResponseStatusError, Schema.TaggedStruct<"ResponseStatusError", {
+    readonly status: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/** A non-2xx response. Carries the status only, never the body. */
+export declare class ResponseStatusError extends ResponseStatusError_base {
+    get message(): string;
+}
+declare const ResponseDecodeError_base: Schema.Class<ResponseDecodeError, Schema.TaggedStruct<"ResponseDecodeError", {}>, import("effect/Cause").YieldableError>;
+/** Invalid JSON or a schema mismatch. Never includes the response body. */
+export declare class ResponseDecodeError extends ResponseDecodeError_base {
+    get message(): string;
+}
+export {};

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

@@ -0,0 +1,26 @@
+/** Browser subscription contracts contain no executable server declarations. */
+import { Schema } from "effect";
+import type { JsonValue } from "./schema.js";
+/** Serializable named reference; the phantom field is never populated at runtime. */
+export interface OperationReference<Input, Output, Kind extends "query" | "mutation"> {
+    readonly name: string;
+    readonly kind: Kind;
+    readonly _types?: {
+        readonly input: Input;
+        readonly output: Output;
+    };
+}
+/** Host-bound subscription request. Authentication and configured app identity belong to the host. */
+export interface QueryDescriptor {
+    readonly name: string;
+    readonly input: JsonValue;
+}
+/** Host transport must close its subscription when async iteration ends. Results are parsed by the client. */
+export interface QueryTransport {
+    readonly subscribe: (descriptor: QueryDescriptor) => Promise<AsyncIterable<unknown>>;
+}
+declare const AppQueryFailed_base: Schema.Class<AppQueryFailed, Schema.TaggedStruct<"AppQueryFailed", {}>, import("effect/Cause").YieldableError>;
+/** Safe client failure; arbitrary transport errors and response data are never exposed. */
+export declare class AppQueryFailed extends AppQueryFailed_base {
+}
+export {};