apps 0.0.1-beta.0

package/types/apps/src/contracts/webhook-protocol.d.ts

@@ -0,0 +1,102 @@
+/** Private host protocol for webhook callbacks. Raw bytes are never parsed as JSON before verification. */
+import { Schema } from "effect";
+/** Raw-byte ceiling shared by callback HTTP, app execution and the encoded host protocol. */
+export declare const WebhookTransportLimits: Schema.Struct<{
+    readonly maxBodyBytes: Schema.Int;
+}>;
+export type WebhookTransportLimits = typeof WebhookTransportLimits.Type;
+/** Requests and responses use the same existing transport bound. */
+export declare const defaultWebhookTransportLimits: {
+    readonly maxBodyBytes: number;
+};
+/** Bounded callback transport. Headers and base64 bytes preserve the provider signature input. */
+export declare const WebhookRequestData: 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;
+}>;
+/** The app response is passed back to the provider after its handler completes. */
+export declare const WebhookResponseData: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly body: Schema.String;
+}>;
+/** Manual instructions are text, never executable HTML. Signing secrets are exchanged only in the setup page. */
+export declare const ManualWebhookSetup: Schema.Struct<{
+    readonly instructions: Schema.NonEmptyString;
+    readonly signingSecret: Schema.Literals<readonly ["executor", "provider"]>;
+}>;
+export type ManualWebhookSetup = typeof ManualWebhookSetup.Type;
+/** The state schema describes the additional private fields collected during manual setup. */
+export declare const ManualWebhookDescriptor: Schema.Struct<{
+    readonly stateSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly instructions: Schema.NonEmptyString;
+    readonly signingSecret: Schema.Literals<readonly ["executor", "provider"]>;
+}>;
+/** Account-bound webhook metadata, evaluated without registering upstream resources. */
+export declare const HostedWebhook: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly account: Schema.NonEmptyString;
+    readonly configSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly setup: Schema.optionalKey<Schema.Struct<{
+        readonly stateSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly instructions: Schema.NonEmptyString;
+        readonly signingSecret: Schema.Literals<readonly ["executor", "provider"]>;
+    }>>;
+}>;
+/** Each command runs with a fresh factory and the subscription's saved account selections. */
+export declare const WebhookCommand: 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">;
+}>]>;
+/** Parsed framework command; contains private host inputs and must not be logged. */
+export type WebhookCommand = typeof WebhookCommand.Type;

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

@@ -0,0 +1,53 @@
+/** Account-bound webhook lifecycle. Register and unregister must be idempotent for subscriptionId. */
+import type { Effect, Schema } from "effect";
+import type { ManualWebhookSetup } from "./webhook-protocol.js";
+import type { AccountSlots, BoundContext } from "./app.js";
+type SourceAccount<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">> = keyof Context["accounts"] & string;
+type SelectedAccount<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">> = {
+    [Slot in keyof Context["accounts"]]: Context["accounts"][Slot] extends readonly (infer Account)[] ? Account : Context["accounts"][Slot];
+}[keyof Context["accounts"]];
+/**
+ * Registration, delivery and cleanup share the selected accounts.
+ * The host stores account IDs and parsed state, never credentials.
+ * Register runs when enabling a subscription, not on every app evaluation.
+ */
+interface WebhookLifecycle<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> {
+    readonly account: SourceAccount<Context>;
+    readonly config: Config;
+    readonly state: State;
+    readonly register: (context: Context, input: {
+        readonly config: Config["Type"];
+        readonly subscriptionId: string;
+        readonly account: SelectedAccount<Context>;
+        readonly callbackUrl: string;
+        readonly secret: string;
+    }) => Effect.Effect<State["Type"], Error>;
+    /** Verify the raw request before acting. */
+    readonly handle: (context: Context, input: {
+        readonly request: Request;
+        readonly config: Config["Type"];
+        readonly subscriptionId: string;
+        readonly account: SelectedAccount<Context>;
+        readonly callbackUrl: string;
+        readonly state: State["Type"] | null;
+        readonly secret: string;
+    }) => Effect.Effect<Response, Error>;
+    /** Remove the upstream registration using its saved state and original account. */
+    readonly unregister: (context: Context, input: {
+        readonly state: State["Type"] | null;
+        readonly config: Config["Type"];
+        readonly subscriptionId: string;
+        readonly account: SelectedAccount<Context>;
+        readonly callbackUrl: string;
+        readonly secret: string;
+    }) => Effect.Effect<void, Error>;
+}
+/** Manual subscriptions collect the state schema in a private browser form instead of invoking provider APIs. */
+export type Webhook<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> = (WebhookLifecycle<Context, Config, State, Error> & {
+    readonly setup?: never;
+}) | (Omit<WebhookLifecycle<Context, Config, State, Error>, "register" | "unregister"> & {
+    readonly setup: typeof ManualWebhookSetup.Type;
+    readonly register?: never;
+    readonly unregister?: never;
+});
+export {};

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

@@ -0,0 +1,277 @@
+/** Portable workflow declarations, run views and durable execution capabilities. */
+import { Schema, type Effect } from "effect";
+import { JsonValue } from "./schema.js";
+import type { AppContext, AppRequirements, QueryContext, MutationContext } from "./context.js";
+import type { Operation } from "../implementation/operations.js";
+import type { HostContext } from "./host.js";
+/** Run identity is opaque and shared by author and SDK interfaces. */
+export declare const WorkflowRunId: Schema.brand<Schema.NonEmptyString, "wfr">;
+export type WorkflowRunId = typeof WorkflowRunId.Type;
+/** Stable names identify declarations and replay steps. */
+export declare const WorkflowName: Schema.NonEmptyString;
+/** Convert portable duration syntax to milliseconds; invalid or overflowing values are rejected. */
+export declare const workflowDurationMillis: (value: number | string) => number | undefined;
+/** Numbers are milliseconds; strings use a quantity and full unit, such as "5 minutes". */
+export declare const WorkflowDuration: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+export type WorkflowDuration = typeof WorkflowDuration.Type;
+/** Author retry and timeout options are passed to the durable engine. */
+export declare const WorkflowStepOptions: Schema.Struct<{
+    readonly retries: Schema.optionalKey<Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly delay: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+        readonly backoff: Schema.optionalKey<Schema.Literals<readonly ["constant", "linear", "exponential"]>>;
+    }>>;
+    readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
+}>;
+export type WorkflowStepOptions = typeof WorkflowStepOptions.Type;
+declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedStruct<"WorkflowFailure", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    readonly retryable: Schema.Boolean;
+}>, import("effect/Cause").YieldableError>;
+/** Safe failures cross host boundaries without authored exceptions or account fields. */
+export declare class WorkflowFailure extends WorkflowFailure_base {
+}
+/** Explicitly stop retrying an authored step. Its message stays inside the app runtime. */
+export declare class NonRetryableError extends Error {
+    readonly name = "NonRetryableError";
+}
+/** Step outputs must fit the engine's persisted JSON result limit. */
+export declare const WorkflowValue: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+/** Live workflow metadata carries schemas rather than executable handlers. */
+export declare const HostedWorkflow: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type HostedWorkflow = typeof HostedWorkflow.Type;
+/** Results are available only on completed runs; failure details are safe reason codes. */
+export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
+    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+    readonly app: Schema.NonEmptyString;
+    readonly deployment: Schema.NonEmptyString;
+    readonly workflow: Schema.NonEmptyString;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"complete">;
+    readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+    readonly app: Schema.NonEmptyString;
+    readonly deployment: Schema.NonEmptyString;
+    readonly workflow: Schema.NonEmptyString;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"errored">;
+    readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+    readonly app: Schema.NonEmptyString;
+    readonly deployment: Schema.NonEmptyString;
+    readonly workflow: Schema.NonEmptyString;
+    readonly createdAt: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"terminated">;
+    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+    readonly app: Schema.NonEmptyString;
+    readonly deployment: Schema.NonEmptyString;
+    readonly workflow: Schema.NonEmptyString;
+    readonly createdAt: Schema.String;
+}>]>;
+export type WorkflowRun = typeof WorkflowRun.Type;
+/** A bounded run-history page, already scoped to an authorized configured app. */
+export declare const WorkflowRunPage: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
+        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+        readonly app: Schema.NonEmptyString;
+        readonly deployment: Schema.NonEmptyString;
+        readonly workflow: Schema.NonEmptyString;
+        readonly createdAt: Schema.String;
+    }>, Schema.Struct<{
+        readonly status: Schema.Literal<"complete">;
+        readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+        readonly app: Schema.NonEmptyString;
+        readonly deployment: Schema.NonEmptyString;
+        readonly workflow: Schema.NonEmptyString;
+        readonly createdAt: Schema.String;
+    }>, Schema.Struct<{
+        readonly status: Schema.Literal<"errored">;
+        readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
+        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+        readonly app: Schema.NonEmptyString;
+        readonly deployment: Schema.NonEmptyString;
+        readonly workflow: Schema.NonEmptyString;
+        readonly createdAt: Schema.String;
+    }>, Schema.Struct<{
+        readonly status: Schema.Literal<"terminated">;
+        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
+        readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
+        readonly app: Schema.NonEmptyString;
+        readonly deployment: Schema.NonEmptyString;
+        readonly workflow: Schema.NonEmptyString;
+        readonly createdAt: Schema.String;
+    }>]>>;
+    readonly next: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "wfr">>;
+}>;
+export type WorkflowRunPage = typeof WorkflowRunPage.Type;
+/** Query and factory contexts may inspect only their own app's runs. */
+export interface WorkflowReads {
+    readonly get: (input: {
+        readonly run: string;
+    }) => Promise<WorkflowRun>;
+    readonly list: (input?: {
+        readonly workflow?: string;
+        readonly limit?: number;
+        readonly cursor?: string;
+    }) => Promise<WorkflowRunPage>;
+}
+/** Mutating handlers may start and terminate runs in their own configured app. */
+export interface WorkflowControls extends WorkflowReads {
+    readonly start: (input: {
+        readonly workflow: string;
+        readonly input: JsonValue;
+        readonly key?: string;
+    }) => Promise<WorkflowRun>;
+    readonly terminate: (input: {
+        readonly run: string;
+    }) => Promise<WorkflowRun>;
+}
+/** External steps get fresh credentials and cancellation, without storage or live elicitation. */
+export type WorkflowStepContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "elicit" | "workflows"> & {
+    readonly runId: WorkflowRunId;
+    readonly stepId: string;
+    readonly idempotencyKey: string;
+};
+/** Explicit durable boundaries; database access passes through registered app operations. */
+export interface WorkflowStep<Requirements extends AppRequirements = AppRequirements> {
+    do<Output>(name: string, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
+    do<Output>(name: string, options: WorkflowStepOptions, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
+    runQuery<Input, Output>(name: string, operation: Operation<Input, Output, "query", QueryContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+    runMutation<Input, Output>(name: string, operation: Operation<Input, Output, "mutation", MutationContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+    readonly sleep: (name: string, duration: WorkflowDuration) => Promise<void>;
+    readonly sleepUntil: (name: string, timestamp: number | Date) => Promise<void>;
+}
+/** The orchestration body gets no account, database or interactive capabilities. */
+export interface WorkflowContext<Requirements extends AppRequirements = AppRequirements> {
+    readonly runId: WorkflowRunId;
+    readonly step: WorkflowStep<Requirements>;
+}
+/** Framework-owned native declaration; only the callback crosses the author Promise boundary. */
+export interface AppWorkflow<Input = unknown, Output = unknown> {
+    readonly description?: string;
+    readonly input: Schema.Decoder<Input>;
+    readonly output?: Schema.Decoder<Output>;
+    readonly run: (context: WorkflowContext, input: Input) => Effect.Effect<Output, unknown>;
+}
+/** The backend supplies checkpoints and timers; app framework code supplies callbacks. */
+export interface WorkflowDriver {
+    readonly do: (name: string, options: WorkflowStepOptions, run: () => Effect.Effect<JsonValue, WorkflowFailure>) => Effect.Effect<JsonValue, WorkflowFailure>;
+    readonly sleep: (name: string, duration: WorkflowDuration) => Effect.Effect<void, WorkflowFailure>;
+    readonly sleepUntil: (name: string, timestamp: number) => Effect.Effect<void, WorkflowFailure>;
+}
+/** Trusted host callbacks for one pinned run. Credentials are resolved only while executing a step. */
+export interface WorkflowExecution {
+    readonly runId: WorkflowRunId;
+    readonly driver: WorkflowDriver;
+    readonly resolve: () => Effect.Effect<HostContext, WorkflowFailure>;
+    readonly invoke: (input: {
+        readonly kind: "query" | "mutation";
+        readonly name: string;
+        readonly input: JsonValue;
+        readonly stepId: string;
+        readonly timeout: number;
+    }) => Effect.Effect<JsonValue, WorkflowFailure>;
+}
+/** Private replay metadata is attached by the host, never accepted in author input. */
+export declare const WorkflowReplay: Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly fingerprint: Schema.NonEmptyString;
+}>;
+export type WorkflowReplay = typeof WorkflowReplay.Type;
+/** Portable discovery, input validation and execution commands. */
+export declare const WorkflowCommand: 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>;
+}>]>;
+export type WorkflowCommand = typeof WorkflowCommand.Type;
+/** Private invocation RPC protocol shared by the host and isolated app bundle. */
+export declare const WorkflowRpcCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"do">;
+    readonly name: Schema.NonEmptyString;
+    readonly options: Schema.Struct<{
+        readonly retries: Schema.optionalKey<Schema.Struct<{
+            readonly limit: Schema.Int;
+            readonly delay: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+            readonly backoff: Schema.optionalKey<Schema.Literals<readonly ["constant", "linear", "exponential"]>>;
+        }>>;
+        readonly timeout: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>>;
+    }>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"sleep">;
+    readonly name: Schema.NonEmptyString;
+    readonly duration: Schema.Union<readonly [Schema.Finite, Schema.NonEmptyString]>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"until">;
+    readonly name: Schema.NonEmptyString;
+    readonly timestamp: Schema.Finite;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"context">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"invoke">;
+    readonly kind: Schema.Literals<readonly ["query", "mutation"]>;
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly stepId: Schema.NonEmptyString;
+    readonly timeout: Schema.Finite;
+}>]>;
+export declare const WorkflowRpcResult: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof WorkflowFailure;
+}>]>;
+export type WorkflowRpcResult = typeof WorkflowRpcResult.Type;
+/** Callback functions are invocation-owned RPC capabilities, never persisted. */
+export type WorkflowRpc = (input: unknown, callback?: () => Promise<unknown>) => Promise<unknown>;
+/** Native app-scoped management capability supplied only by an authorized host invocation. */
+export interface WorkflowHostControls {
+    readonly start: (input: Parameters<WorkflowControls["start"]>[0]) => Effect.Effect<WorkflowRun, WorkflowFailure>;
+    readonly get: (input: Parameters<WorkflowControls["get"]>[0]) => Effect.Effect<WorkflowRun, WorkflowFailure>;
+    readonly list: (input: Parameters<WorkflowControls["list"]>[0]) => Effect.Effect<WorkflowRunPage, WorkflowFailure>;
+    readonly terminate: (input: Parameters<WorkflowControls["terminate"]>[0]) => Effect.Effect<WorkflowRun, WorkflowFailure>;
+}
+/** Serializable requests do not contain an app ID; authority is captured in the supplied capability. */
+export declare const WorkflowControlCommand: Schema.Union<readonly [Schema.Struct<{
+    readonly operation: Schema.Literal<"start">;
+    readonly workflow: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly key: Schema.optionalKey<Schema.NonEmptyString>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"get">;
+    readonly run: Schema.brand<Schema.NonEmptyString, "wfr">;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"list">;
+    readonly workflow: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly cursor: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "wfr">>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>, Schema.Struct<{
+    readonly operation: Schema.Literal<"terminate">;
+    readonly run: Schema.brand<Schema.NonEmptyString, "wfr">;
+}>]>;
+export {};

package/types/apps/src/effect.d.ts

@@ -0,0 +1,10 @@
+/** Native schema interop for app libraries written in Effect; ordinary authors use apps. */
+export { HttpUrl, JsonObject, type JsonValue, ValidationError } from "./contracts/schema.js";
+export { compileJsonSchemaDecoder, jsonSchemaDecoder, decoderOf, wrap, } from "./implementation/schema.js";
+export type { PromiseMethods } from "./implementation/authoring.js";
+export { ToolAnnotations } from "./contracts/tools.js";
+export { ApprovalDecision, type Approval, type ApprovalContext } from "./contracts/approval.js";
+/** Native host dispatch for trusted bundled apps; credentials remain invocation-local. */
+export { createAppHandler } from "./implementation/host.js";
+/** Parse a form and build its response parser for a host-owned interaction. */
+export { prepareElicitation } from "./implementation/elicitation.js";

package/types/apps/src/facet.d.ts

@@ -0,0 +1,5 @@
+/** Native workerd SQLite capability; used only by the generated data facet, never browser bundles. */
+import * as Sqlite from "@effect/sql-sqlite-do/SqliteClient";
+import type { AppStorage } from "./contracts/storage.js";
+/** Bind one facet's raw storage at the runtime edge. Each operation owns its native SQL scope. */
+export declare const facetStorage: (storage: NonNullable<Sqlite.SqliteClientConfig["storage"]>) => AppStorage;

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

@@ -0,0 +1,10 @@
+/** GraphQL helpers. Requires the optional graphql peer. */
+import { type OperationKinds } from "./implementation/protocol-operations.js";
+import type { GraphqlToolsOptions } from "./contracts/graphql.js";
+export { GraphqlError, type GraphqlToolsOptions } from "./contracts/graphql.js";
+/** Discover operations for the selected account. Kinds override uncertain upstream read-only hints. */
+export declare const graphqlOperations: (options: GraphqlToolsOptions, kinds?: OperationKinds) => Promise<{
+    queries: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "query", import("./index.js").OperationContext>>;
+    mutations: Record<string, import("./index.js").Operation<import("effect/Schema").Json, unknown, "mutation", import("./index.js").OperationContext>>;
+}>;
+export type { OperationKinds } from "./implementation/protocol-operations.js";

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

@@ -0,0 +1,16 @@
+import { type HostContext, type ResolvedAccountsInput } from "./contracts/host.js";
+import { type ElicitationHandler } from "./contracts/elicitation.js";
+export type { HostContext, ResolvedAccountsInput } from "./contracts/host.js";
+/** Parse trusted account bindings and an optional exact-call approval. Throws safe boundary errors on invalid input. */
+export declare const hostContext: (accounts: ResolvedAccountsInput, approval?: unknown) => HostContext;
+/** Portable Promise handler. Invoke only after the host has authorized and resolved accounts. */
+export declare const createAppHandler: (app: unknown) => ((request: Request, context: HostContext) => Promise<Response>);
+/** Isolates return bounded, telemetry beside the protocol result; no exporter secret enters app code. */
+export declare const createIsolatedAppHandler: (app: unknown) => (request: Request, context: HostContext) => Promise<Response>;
+/**
+ * Adapt a host-owned RPC callback into the handler an isolated app expects. Generated entry
+ * points call this instead of depending on Effect, which the app bundle cannot resolve.
+ * A transport failure aborts the lifetime so the invocation stops waiting.
+ */
+export declare const isolatedElicitation: (deliver: (request: unknown) => Promise<unknown>, lifetime: AbortController) => ElicitationHandler;
+export { isolatedWorkflowExecution, isolatedWorkflowControls, } from "./implementation/workflow-rpc.js";

package/types/apps/src/implementation/account-operations.d.ts

@@ -0,0 +1,32 @@
+import type { OperationContext } from "../contracts/operations.js";
+import { type JsonValue } from "../contracts/schema.js";
+import { type Operation } from "./operations.js";
+type Operations = {
+    readonly queries: Readonly<Record<string, Operation<JsonValue, unknown, "query", OperationContext>>>;
+    readonly mutations: Readonly<Record<string, Operation<JsonValue, unknown, "mutation", OperationContext>>>;
+};
+/**
+ * Discover each selected account's protocol operations and combine matching names.
+ * Calls take { accountId, input }; each branch retains its account's input schema,
+ * credentials, approval and output validation. Empty selections expose no operations.
+ * Discovery is sequential and cancellation follows the caller's signal.
+ */
+export declare const accountOperations: <Account extends {
+    readonly id: string;
+}>(accounts: readonly Account[], discover: (account: Account) => Promise<Operations>, options: {
+    readonly signal: AbortSignal;
+}) => Promise<{
+    queries: {
+        [k: string]: Operation<{
+            readonly accountId: string;
+            readonly input: unknown;
+        }, unknown, "query", import("../index.js").AppContext>;
+    };
+    mutations: {
+        [k: string]: Operation<{
+            readonly accountId: string;
+            readonly input: unknown;
+        }, unknown, "mutation", import("../index.js").AppContext>;
+    };
+}>;
+export {};

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

@@ -0,0 +1,40 @@
+import type { ScheduleDeclaration } from "./schedules.js";
+import type { App as NativeApp, AppDefinition as NativeDefinition } from "../contracts/app.js";
+import type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext } from "../contracts/context.js";
+import { type PromiseMethods } from "./authoring.js";
+import { type WorkflowDeclaration } from "./workflows.js";
+import type { WorkflowContext } from "../contracts/workflows.js";
+import { type OperationDeclaration } from "./operations.js";
+import { type Schema } from "./schema.js";
+type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>> ? {
+    readonly [Name in keyof Catalog]: {
+        readonly [Key in keyof Catalog[Name]]: Key extends "config" | "state" ? Schema<unknown, boolean> : PromiseMethods<Catalog[Name]>[Key];
+    };
+} : Catalog;
+/** Author definition projected from native capabilities. Excluding callable objects keeps
+ * factories from being inferred as definitions and preserves contextual handler inference. */
+export type AppDefinition<Requirements extends AppRequirements> = {
+    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "queries" ? Readonly<Record<string, OperationDeclaration<"query", QueryContext<Requirements>>>> : Key extends "mutations" ? Readonly<Record<string, OperationDeclaration<"mutation", MutationContext<Requirements>>>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
+} & {
+    readonly name?: never;
+    readonly tools?: never;
+    readonly call?: never;
+};
+/** Adapt operation and webhook catalogs without evaluating their handlers. */
+export type EffectDefinition<Def> = {
+    readonly [Key in keyof Def]: Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "queries" | "mutations" ? Readonly<Record<string, import("../contracts/operations.js").AppOperation>> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Def[Key];
+};
+declare const InternalApp: unique symbol;
+/** Recognize a declaration from this framework instance before host adaptation. */
+export declare const isApp: (value: unknown) => value is App<AppRequirements, AppDefinition<AppRequirements>>;
+/** Public app handle; the native app is retained for host use without an async round trip. */
+export interface App<Requirements extends AppRequirements, Def extends AppDefinition<Requirements>> {
+    readonly [InternalApp]: NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
+    readonly accounts: Requirements["accounts"];
+    readonly evaluate: (context: AppContext<Requirements>) => Promise<Def>;
+}
+/** Retrieve the same declaration for an Effect host. No evaluation or I/O occurs. */
+export declare const toEffectApp: <Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(app: App<Requirements, Def>) => NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
+/** Assemble app behavior. Package names belong in package.json; hosts name installed copies. */
+export declare const defineApp: <const Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(requirements: Requirements, definition: (Def & AppDefinition<Requirements>) | ((context: AppContext<Requirements>) => Promise<Def & AppDefinition<Requirements>>)) => App<Requirements, Def>;
+export {};

package/types/apps/src/implementation/authoring.d.ts

@@ -0,0 +1,12 @@
+/** Small, explicit adapters between authored callbacks and native Effect operations. */
+import { Effect } from "effect";
+/** Project one Effect operation into its author-facing Promise signature. */
+export type PromiseMethod<Method> = Method extends (...args: infer Args) => Effect.Effect<infer A, infer _E> ? (...args: Args) => Promise<A> : Method;
+/** Project only an object's methods; data and schema types are not recursively rewritten. */
+export type PromiseMethods<T> = {
+    readonly [Key in keyof T]: PromiseMethod<T[Key]>;
+};
+/** Reuse a framework callback's cancellation-bound Effect, or adapt an ordinary async callback. */
+export declare const fromPromise: <Args extends readonly unknown[], A>(callback: (...args: Args) => Promise<A>) => ((...args: Args) => Effect.Effect<A, unknown>);
+/** Bind cancellation once so Promise callers and native framework callers run the same operation. */
+export declare const toPromise: <Args extends readonly unknown[], A, E>(operation: (...args: Args) => Effect.Effect<A, E>, signal?: AbortSignal) => ((...args: Args) => Promise<A>);