@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/DualRuntime.ts

@@ -0,0 +1,1081 @@
+/**
+ * Dual action invocation, trigger lifecycle, and auth runtime.
+ *
+ * @since 0.0.0
+ */
+import {
+  Array,
+  Context,
+  Effect,
+  Function as Func,
+  Layer,
+  Predicate,
+  Result,
+  Schema,
+  pipe,
+} from "effect";
+
+import { type HttpClientRequest, Url } from "effect/http";
+
+import {
+  ActionHandlerError,
+  RetryableActionHandlerError,
+  type ActionHandlerFailure,
+} from "./Action.ts";
+import * as AgentChannelRuntime from "./AgentChannelRuntime.ts";
+import * as AiProvider from "./AiProvider.ts";
+import type * as AuthMethod from "./AuthMethod.ts";
+import * as AuthMethodBinding from "./AuthMethodBinding.ts";
+import * as AuthMethodExecution from "./AuthMethodExecution.ts";
+import {
+  ConnectionIdNotAllowedError,
+  ConnectionReauthorizationRequiredError,
+  ConnectionRequiredError,
+  ConnectionSelectionRequiredError,
+  ConnectionResolverStoreError,
+  InvalidConnectionIdError,
+  InvalidResolvedConnectionError,
+  type ConnectionResolutionContext,
+} from "./ConnectionResolver.ts";
+import { BuilderCollisionError } from "./DefinitionError.ts";
+import { TriggerNotFoundError } from "./DualRegistry.ts";
+import { authRuntimeContext } from "./internal/auth-execution.ts";
+import { resolveAction, type PluginActions } from "./internal/dual/actions.ts";
+import {
+  ActionNotFoundError,
+  FieldIssue,
+  InvalidActionInputError,
+  InvalidActionOutputError,
+  ActionHandlerNotFoundError,
+  type InvokeError,
+  type InvokeMeta,
+  type InvokeRequest,
+  type InvokeRequirementsFor,
+  type InvokeSuccess,
+  type PluginRequirements,
+  invokeResolvedAction,
+  invokeResolvedActionJson,
+} from "./internal/dual/invoke.ts";
+import { resolveRuntimeTrigger } from "./internal/dual/triggers.ts";
+import { indexGroups } from "./internal/handler-context.ts";
+import type * as Plugin from "./Plugin.ts";
+import * as Trigger from "./Trigger.ts";
+
+/**
+ * One installed plugin release.
+ *
+ * @since 0.7.0
+ * @category models
+ */
+export interface PluginInstallation<P extends Plugin.Any = Plugin.Any> {
+  readonly plugin: P;
+  /** The plugin's package version. */
+  readonly version: string;
+}
+
+/**
+ * The plugin releases and AI providers one runtime executes, with the services their handlers need.
+ *
+ * @since 0.7.0
+ * @category models
+ */
+export interface App<
+  out P extends Plugin.Any = Plugin.Any,
+  LayerOutput = never,
+  out LayerError = never,
+  out LayerRequirements = never,
+  out AiProviders extends readonly AiProvider.Any[] = readonly AiProvider.Any[],
+> {
+  readonly identifier: string;
+  readonly aiProviders: AiProviders;
+  readonly plugins: readonly PluginInstallation<P>[];
+  readonly layer: Layer.Layer<LayerOutput, LayerError, LayerRequirements>;
+}
+
+/**
+ * Constraint type for working with any {@link App}.
+ *
+ * @since 0.7.0
+ * @category type-level
+ */
+export interface AnyApp extends App<Plugin.Any, never, any, any, readonly AiProvider.Any[]> {}
+
+/**
+ * Install one plugin release.
+ *
+ * @since 0.7.0
+ * @category constructors
+ */
+export const install = <P extends Plugin.Any>(
+  plugin: P,
+  version: string,
+): PluginInstallation<P> => ({ plugin, version });
+
+/**
+ * The runtime of one plugin release, as the plugin's own process runs it. `version` defaults to
+ * `0.0.0` for tests that do not need the package version.
+ *
+ * @since 0.7.0
+ * @category constructors
+ */
+export const fromPlugin = <const P extends Plugin.Any>(
+  plugin: P,
+  version = "0.0.0",
+): App<
+  P,
+  Plugin.LayerOutput<readonly [P]>,
+  Plugin.LayerError<readonly [P]>,
+  Plugin.LayerRequirements<readonly [P]>,
+  readonly []
+> =>
+  ({
+    aiProviders: [],
+    identifier: plugin.identifier,
+    layer: plugin.layer,
+    plugins: [install(plugin, version)],
+  }) as never;
+
+/**
+ * An app runtime without plugins, for {@link withPlugin} and {@link withPlugins} to fill.
+ *
+ * @since 0.7.0
+ * @category constructors
+ */
+export const make = (identifier: string): App<never, never, never, never, readonly []> => ({
+  aiProviders: [],
+  identifier,
+  layer: Layer.empty,
+  plugins: [],
+});
+
+type AppPlugin<A extends AnyApp> = A extends App<infer P, any, any, any, any> ? P : never;
+type AppLayerOutput<A extends AnyApp> =
+  A extends App<any, infer Output, any, any, any> ? Output : never;
+type AppLayerError<A extends AnyApp> =
+  A extends App<any, any, infer Error, any, any> ? Error : never;
+type AppLayerRequirements<A extends AnyApp> =
+  A extends App<any, any, any, infer Requirements, any> ? Requirements : never;
+
+/**
+ * Result of adding a plugin release to an app runtime. A named interface keeps declaration emit
+ * from expanding every plugin and layer member at large call sites.
+ *
+ * @since 0.7.0
+ * @category type-level
+ */
+export interface WithPlugin<Self extends AnyApp, Added extends Plugin.Any> extends App<
+  AppPlugin<Self> | Added,
+  AppLayerOutput<Self> | Plugin.LayerOutput<readonly [Added]>,
+  AppLayerError<Self> | Plugin.LayerError<readonly [Added]>,
+  | Plugin.LayerRequirements<readonly [Added]>
+  | Exclude<AppLayerRequirements<Self>, Plugin.LayerOutput<readonly [Added]>>,
+  Self["aiProviders"]
+  // oxlint-disable-next-line typescript/no-empty-object-type -- TypeScript declaration emit expands a type alias at every app call site (TS7056).
+> {}
+
+// Match the runtime's left-to-right provideMerge fold: later plugins can
+// satisfy earlier requirements, but earlier outputs cannot satisfy later ones.
+type BulkLayerRequirements<
+  Added extends readonly Plugin.Any[],
+  Requirements,
+> = number extends Added["length"]
+  ? Requirements | Layer.Services<Added[number]["layer"]>
+  : Added extends readonly [
+        infer Head extends Plugin.Any,
+        ...infer Tail extends readonly Plugin.Any[],
+      ]
+    ? BulkLayerRequirements<
+        Tail,
+        Layer.Services<Head["layer"]> | Exclude<Requirements, Layer.Success<Head["layer"]>>
+      >
+    : Requirements;
+
+/**
+ * Result of adding several plugin releases to an app runtime in one step.
+ *
+ * @since 0.7.0
+ * @category type-level
+ */
+export interface WithPlugins<Self extends AnyApp, Added extends readonly Plugin.Any[]> extends App<
+  AppPlugin<Self> | Added[number],
+  AppLayerOutput<Self> | Layer.Success<Added[number]["layer"]>,
+  AppLayerError<Self> | Layer.Error<Added[number]["layer"]>,
+  BulkLayerRequirements<Added, AppLayerRequirements<Self>>,
+  Self["aiProviders"]
+  // oxlint-disable-next-line typescript/no-empty-object-type -- TypeScript declaration emit expands a type alias at every app call site (TS7056).
+> {}
+
+/** A plugin and the package version of its release. */
+type PluginEntry = readonly [plugin: Plugin.Any, version: string];
+
+type PluginsOf<Entries extends readonly PluginEntry[]> = {
+  readonly [K in keyof Entries]: Entries[K][0];
+};
+
+function addPlugins(app: AnyApp, entries: readonly PluginEntry[]): AnyApp {
+  const seen = new Set(Array.map(app.plugins, installation => installation.plugin.identifier));
+  for (const [plugin] of entries) {
+    if (seen.has(plugin.identifier)) {
+      throw new BuilderCollisionError({
+        childKind: "plugin",
+        existingChildKind: "plugin",
+        identifier: plugin.identifier,
+        ownerIdentifier: app.identifier,
+        ownerKind: "dual",
+      });
+    }
+    seen.add(plugin.identifier);
+  }
+  return {
+    ...app,
+    layer: Array.reduce(entries, app.layer, (layer, [plugin]) =>
+      Layer.provideMerge(layer, plugin.layer),
+    ),
+    plugins: [
+      ...app.plugins,
+      ...Array.map(entries, ([plugin, version]) => install(plugin, version)),
+    ],
+  };
+}
+
+/**
+ * Add one plugin release: the plugin and its package version.
+ *
+ * @since 0.7.0
+ * @category combinators
+ */
+export const withPlugin: {
+  <const P extends Plugin.Any>(
+    plugin: P,
+    version: string,
+  ): <Self extends AnyApp>(app: Self) => WithPlugin<Self, P>;
+  <Self extends AnyApp, const P extends Plugin.Any>(
+    app: Self,
+    plugin: P,
+    version: string,
+  ): WithPlugin<Self, P>;
+} = Func.dual(3, (app: AnyApp, plugin: Plugin.Any, version: string) =>
+  addPlugins(app, [[plugin, version]]),
+);
+
+/**
+ * Add several plugin releases in one step, which keeps a large app's inferred type compact.
+ *
+ * @since 0.7.0
+ * @category combinators
+ */
+export const withPlugins: {
+  <const E extends readonly PluginEntry[]>(
+    entries: E,
+  ): <Self extends AnyApp>(app: Self) => WithPlugins<Self, PluginsOf<E>>;
+  <Self extends AnyApp, const E extends readonly PluginEntry[]>(
+    app: Self,
+    entries: E,
+  ): WithPlugins<Self, PluginsOf<E>>;
+} = Func.dual(2, addPlugins);
+
+const pluginOf = (app: AnyApp, identifier: string): Plugin.Any | undefined =>
+  app.plugins.find(installation => installation.plugin.identifier === identifier)?.plugin;
+
+/**
+ * Request payload accepted by {@link invoke}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type { InvokeRequest };
+
+/**
+ * Metadata returned alongside successful invocation data.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type { InvokeMeta };
+
+/**
+ * Successful invocation envelope returned by {@link invoke}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type { InvokeSuccess };
+
+/**
+ * Structured field-level validation issue surfaced by {@link InvalidActionInputError}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export { FieldIssue };
+
+/**
+ * Raised when an invocation references an unknown action id.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ActionNotFoundError };
+
+/**
+ * @since 0.0.0
+ * @category errors
+ */
+
+/**
+ * Raised when invocation input fails schema validation.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { InvalidActionInputError };
+
+/**
+ * Raised when action handler output fails schema validation.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { InvalidActionOutputError };
+
+/**
+ * Raised when the runtime action handler service is missing.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ActionHandlerNotFoundError };
+
+/**
+ * Non-retryable failure reported by a trusted action handler.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ActionHandlerError };
+
+/**
+ * Retryable failure reported by a trusted action handler.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { RetryableActionHandlerError };
+
+/**
+ * Stable trusted action handler failure contract.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export type { ActionHandlerFailure };
+
+/**
+ * Raised when an action does not accept a connection but a connectionId was still provided.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ConnectionIdNotAllowedError };
+
+/**
+ * Raised when invocation requires a connection and no compatible binding is available.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ConnectionRequiredError };
+
+/**
+ * Raised when several compatible connection bindings exist and the caller must choose one.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ConnectionSelectionRequiredError };
+
+/**
+ * Raised when the provider refuses a connection's stored grant and the user must sign in again.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ConnectionReauthorizationRequiredError };
+
+/**
+ * Raised when the host connection store is unavailable.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { ConnectionResolverStoreError };
+
+/**
+ * Raised when a connectionId does not resolve to a compatible binding.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { InvalidConnectionIdError };
+
+/**
+ * Raised when a resolved connection binding does not satisfy its auth method schema.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export { InvalidResolvedConnectionError };
+
+/**
+ * Structured SDK-owned invocation failures.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export type { InvokeError };
+export type { InvokeRequirementsFor };
+
+/**
+ * Invoke an action directly in-process.
+ *
+ * The invocation boundary resolves an action by canonical machine id, validates
+ * unknown input against the resolved runtime schema, runs the handler, and
+ * returns a standard success envelope. This mirrors the server trusted invoke
+ * boundary: runtime schema validation is authoritative.
+ *
+ * @since 0.0.0
+ * @category execution
+ */
+const failInvokeActionNotFound = (
+  actionId: string,
+): Effect.Effect<InvokeSuccess, ActionNotFoundError> =>
+  Effect.fail(new ActionNotFoundError({ actionId }));
+
+const invokeRaw = <
+  const P extends Plugin.Any,
+  LayerOutput,
+  LayerError,
+  LayerRequirements,
+  const AiProviders extends readonly AiProvider.Any[],
+>(
+  app: App<P, LayerOutput, LayerError, LayerRequirements, AiProviders>,
+  request: InvokeRequest,
+  json = false,
+): Effect.Effect<InvokeSuccess, InvokeError, RuntimeRequirementsFor<P>> => {
+  const resolved = resolveAction(app.plugins, request.actionId, request.actionVersion);
+
+  if (
+    resolved === undefined ||
+    (request.pluginKey !== undefined && resolved.providerId !== request.pluginKey)
+  ) {
+    return failInvokeActionNotFound(request.actionId);
+  }
+
+  // The runtime entry is resolved from erased plugin trees, so the precise
+  // per-action requirement union in the return annotation cannot be recovered
+  // here; the annotation is the contract, the cast is the boundary.
+  return (json ? invokeResolvedActionJson : invokeResolvedAction)(
+    resolved.providerId,
+    resolved.actionId,
+    resolved.pluginVersion,
+    resolved.action,
+    resolved.authMethods,
+    request,
+  ) as never;
+};
+
+export const invoke = <
+  const P extends Plugin.Any,
+  LayerOutput,
+  LayerError,
+  LayerRequirements,
+  const AiProviders extends readonly AiProvider.Any[],
+>(
+  app: App<P, LayerOutput, LayerError, LayerRequirements, AiProviders>,
+  request: InvokeRequest,
+): Effect.Effect<
+  InvokeSuccess,
+  InvokeError | LayerError,
+  LayerRequirements | Exclude<RuntimeRequirementsFor<P>, LayerOutput>
+> => invokeRaw(app, request).pipe(Effect.provide(app.layer));
+
+/**
+ * Runtime-first invocation request accepted by {@link Service}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type RuntimeInvokeRequest = InvokeRequest;
+
+/**
+ * Runtime-first trigger lifecycle request accepted by {@link Service}.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface RuntimeTriggerLifecycleRequest {
+  readonly triggerId: string;
+  readonly pluginKey?: string;
+  /** The exact plugin release the caller pinned; another installed release does not run. */
+  readonly triggerVersion?: string | undefined;
+  readonly config: unknown;
+  readonly state?: unknown | undefined;
+  readonly connectionId?: string | undefined;
+  readonly context?: ConnectionResolutionContext | undefined;
+}
+
+export interface RuntimeWebhookActivationRequest extends RuntimeTriggerLifecycleRequest {
+  readonly webhookUrl: string;
+}
+
+export interface RuntimeWebhookTriggerLifecycleRequest extends RuntimeWebhookActivationRequest {
+  readonly request: Trigger.WebhookRequest;
+}
+
+export interface AuthMethodRequest {
+  readonly providerId: string;
+  readonly authMethodId: string;
+}
+
+export interface DecodeAuthMethodSetupRequest extends AuthMethodRequest {
+  readonly encoding?: "json";
+  readonly setup: unknown;
+}
+
+export interface PrepareAuthMethodRequest extends AuthMethodRequest {
+  readonly input: unknown;
+  readonly setup: unknown;
+}
+
+export interface PrepareOAuth2TokensRequest extends AuthMethodRequest {
+  readonly tokens: AuthMethod.OAuth2TokenResponse;
+  readonly setup: unknown;
+}
+
+export interface RefreshAuthMethodRequest extends AuthMethodRequest {
+  readonly material: unknown;
+  readonly setup: unknown;
+  readonly now: number;
+  readonly minValidityMs: number;
+  readonly reason: AuthMethod.RefreshReason;
+}
+
+export interface ResolveAuthMethodRequest extends AuthMethodRequest {
+  /** `json` when the material and setup arrive in their canonical JSON encoding, as in the sandbox. */
+  readonly encoding?: "json";
+  readonly material: unknown;
+  readonly setup: unknown;
+}
+
+export interface ResolveAiModelConfigRequest extends ResolveAuthMethodRequest {
+  readonly model: AiProvider.RuntimeModel;
+}
+
+export class AuthMethodNotFoundError extends Schema.TaggedError<AuthMethodNotFoundError>()(
+  "AuthMethodNotFoundError",
+  { authMethodId: Schema.String, providerId: Schema.String },
+) {}
+
+export type AuthMethodExecutionError =
+  | AuthMethodNotFoundError
+  | Schema.SchemaError
+  | AuthMethod.ExpectedOAuth2MethodError
+  | AuthMethod.OAuth2RefreshTokenUnavailableError
+  | AuthMethod.AuthMethodHookError;
+
+export class AiProviderRuntimeNotConfiguredError extends Schema.TaggedError<AiProviderRuntimeNotConfiguredError>()(
+  "AiProviderRuntimeNotConfiguredError",
+  { providerId: Schema.String },
+) {}
+
+export type AiModelConfigError = AuthMethodExecutionError | AiProviderRuntimeNotConfiguredError;
+
+/** Raised when a provider declares no sandbox access. */
+export class SandboxAccessNotDeclaredError extends Schema.TaggedError<SandboxAccessNotDeclaredError>()(
+  "SandboxAccessNotDeclaredError",
+  { providerId: Schema.String },
+) {}
+
+/** Raised when the Connection may not be sent with a sandbox request: another origin, or a request the provider refuses. */
+export class SandboxRequestNotAllowedError extends Schema.TaggedError<SandboxRequestNotAllowedError>()(
+  "SandboxRequestNotAllowedError",
+  { origin: Schema.String, path: Schema.String, providerId: Schema.String },
+) {}
+
+export type SandboxAccessError = AuthMethodExecutionError | SandboxAccessNotDeclaredError;
+
+/** One Connection's sandbox access: where its credential may go, and how a request gets it. */
+export interface ResolvedSandboxAccess {
+  readonly origins: readonly string[];
+  readonly authorize: (
+    request: HttpClientRequest.HttpClientRequest,
+  ) => Effect.Effect<HttpClientRequest.HttpClientRequest, SandboxRequestNotAllowedError>;
+}
+
+/**
+ * Runtime service materialized from an {@link App}.
+ *
+ * @since 0.0.0
+ * @category services
+ */
+export interface RuntimeService {
+  readonly executeAuthJson: (
+    request: AuthMethodExecution.JsonRequest,
+  ) => Effect.Effect<unknown, AuthMethodExecutionError>;
+  readonly invokeJson: (
+    request: RuntimeInvokeRequest,
+  ) => Effect.Effect<InvokeSuccess<string, Schema.Json>, InvokeError | Schema.SchemaError>;
+  readonly decodeAgentChannelDefinitionSettings: AgentChannelRuntime.Interface["decodeDefinitionSettings"];
+  readonly decodeAgentChannelDeploymentSettings: AgentChannelRuntime.Interface["decodeDeploymentSettings"];
+  readonly getAgentChannel: AgentChannelRuntime.Interface["get"];
+  readonly checkAccessAgentChannel: AgentChannelRuntime.Interface["checkAccess"];
+  readonly executeAgentChannel: AgentChannelRuntime.Interface["execute"];
+  readonly invoke: (request: RuntimeInvokeRequest) => Effect.Effect<InvokeSuccess, InvokeError>;
+  readonly activateTrigger: (
+    request: RuntimeWebhookActivationRequest,
+  ) => Effect.Effect<Trigger.ActivateSuccess, unknown>;
+  readonly deactivateTrigger: (
+    request: RuntimeWebhookActivationRequest,
+  ) => Effect.Effect<Trigger.DeactivateSuccess, unknown>;
+  readonly verifyTrigger: (
+    request: RuntimeWebhookTriggerLifecycleRequest,
+  ) => Effect.Effect<Trigger.VerifySuccess, unknown>;
+  readonly parseTrigger: (
+    request: RuntimeWebhookTriggerLifecycleRequest,
+  ) => Effect.Effect<Trigger.EmittedEventsSuccess<string, "parse">, unknown>;
+  readonly pollTrigger: (
+    request: RuntimeTriggerLifecycleRequest,
+  ) => Effect.Effect<Trigger.EmittedEventsSuccess<string, "poll">, unknown>;
+  readonly getAuthMethod: (
+    request: AuthMethodRequest,
+  ) => Effect.Effect<AuthMethod.Any, AuthMethodNotFoundError>;
+  // TODO(live-schema-validation): expose live action/trigger schema decoders by capability version.
+  // Server authoring/runtime must validate against SDK declarations, not JSON Schema projections.
+  readonly decodeAuthMethodSetup: (
+    request: DecodeAuthMethodSetupRequest,
+  ) => Effect.Effect<unknown, AuthMethodExecutionError>;
+  readonly prepareAuthMethod: (
+    request: PrepareAuthMethodRequest,
+  ) => Effect.Effect<unknown, AuthMethodExecutionError>;
+  readonly prepareOAuth2Tokens: (
+    request: PrepareOAuth2TokensRequest,
+  ) => Effect.Effect<unknown, AuthMethodExecutionError>;
+  readonly refreshAuthMethod: (
+    request: RefreshAuthMethodRequest,
+  ) => Effect.Effect<unknown | undefined, AuthMethodExecutionError>;
+  readonly resolveAuthMethod: (
+    request: ResolveAuthMethodRequest,
+  ) => Effect.Effect<AuthMethodBinding.Binding, AuthMethodExecutionError>;
+  readonly resolveAiModelConfig: (
+    request: ResolveAiModelConfigRequest,
+  ) => Effect.Effect<AiProvider.RuntimeConfig, AiModelConfigError>;
+  readonly resolveSandboxAccess: (
+    request: ResolveAuthMethodRequest,
+  ) => Effect.Effect<ResolvedSandboxAccess, SandboxAccessError>;
+}
+
+/**
+ * Effect service provided by {@link toLayer}.
+ *
+ * @since 0.0.0
+ * @category services
+ */
+export class Service extends Context.Service<Service, RuntimeService>()(
+  "@dual-os/sdk/Dual/Service",
+) {}
+
+export type RuntimeRequirementsFor<P extends Plugin.Any> =
+  | AgentChannelRuntime.Requirements<P>
+  | (P extends Plugin.Any ? PluginRequirements<P, PluginActions<P>> : never);
+
+type AuthProvider = Plugin.Any | AiProvider.Any;
+
+type AuthMethodFor<Providers extends AuthProvider> = Providers["authMethods"][number];
+
+type AuthMethodSetupDecodeRequirements<Method extends AuthMethod.Any> =
+  AuthMethod.SetupSchema<Method> extends Schema.Top
+    ? Schema.Codec.DecodingServices<AuthMethod.SetupSchema<Method>>
+    : never;
+
+type AuthMethodInputDecodeRequirements<Method extends AuthMethod.Any> =
+  AuthMethod.InputSchema<Method> extends Schema.Top
+    ? Schema.Codec.DecodingServices<AuthMethod.InputSchema<Method>>
+    : never;
+
+type AuthMethodExecutionRequirementsFor<Providers extends AuthProvider> =
+  AuthMethodFor<Providers> extends infer Method
+    ? Method extends AuthMethod.Any
+      ?
+          | AuthMethod.Requirements<Method>
+          | AuthMethodSetupDecodeRequirements<Method>
+          | AuthMethodInputDecodeRequirements<Method>
+          | Schema.Codec.DecodingServices<AuthMethod.MaterialSchema<Method>>
+          | Schema.Codec.DecodingServices<AuthMethod.ValueSchema<Method>>
+          | Schema.Codec.EncodingServices<AuthMethod.MaterialSchema<Method>>
+          | Schema.Codec.EncodingServices<AuthMethod.ValueSchema<Method>>
+          | (AuthMethod.SetupSchema<Method> extends Schema.Top
+              ? Schema.Codec.EncodingServices<AuthMethod.SetupSchema<Method>>
+              : never)
+      : never
+    : never;
+
+/**
+ * Requirements still needed by {@link toLayer} for an app.
+ *
+ * Hosts (the server, a worker, a test harness) never know an app's concrete
+ * implementations: they talk to it exclusively through the generic
+ * {@link Service} layer. App-specific dependencies — a plugin's API client, an
+ * auth hook's token service — are discharged where they are known, at the
+ * plugin or app definition (the `Exclude<..., LayerOutput>` below cancels
+ * them). Only what the definition did not discharge surfaces here,
+ * generically, and the host entrypoint forces it to `never` before anything
+ * runs.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type ToLayerRequirements<A extends AnyApp> =
+  A extends App<
+    infer P extends Plugin.Any,
+    infer LayerOutput,
+    any,
+    infer LayerRequirements,
+    infer AiProviders extends readonly AiProvider.Any[]
+  >
+    ?
+        | LayerRequirements
+        | Exclude<RuntimeRequirementsFor<P>, LayerOutput>
+        | Exclude<AuthMethodExecutionRequirementsFor<P | AiProviders[number]>, LayerOutput>
+    : never;
+
+/**
+ * Layer-construction errors surfaced by {@link toLayer} for an app.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type ToLayerError<A extends AnyApp> =
+  A extends App<any, any, infer LayerError, any, any> ? LayerError : never;
+
+/**
+ * Turn an {@link App} into a runtime Effect service layer.
+ *
+ * @since 0.0.0
+ * @category layers
+ */
+export const toLayer = <
+  const P extends Plugin.Any,
+  LayerOutput,
+  LayerError,
+  LayerRequirements,
+  const AiProviders extends readonly AiProvider.Any[],
+>(
+  app: App<P, LayerOutput, LayerError, LayerRequirements, AiProviders>,
+): Layer.Layer<
+  Service,
+  LayerError,
+  | LayerRequirements
+  | Exclude<RuntimeRequirementsFor<P>, LayerOutput>
+  | Exclude<AuthMethodExecutionRequirementsFor<P | AiProviders[number]>, LayerOutput>
+> => {
+  const fullAuthMethodId = (providerId: string, method: AuthMethod.Any): string =>
+    `${providerId}/${method.identifier}`;
+
+  const findAuthMethod = (
+    providerId: string,
+    authMethodId: string,
+  ): Effect.Effect<AuthMethod.Any, AuthMethodNotFoundError> => {
+    const provider =
+      pluginOf(app, providerId) ??
+      app.aiProviders.find(candidate => AiProvider.registryId(candidate.identifier) === providerId);
+    const method = provider?.authMethods.find(
+      candidate =>
+        candidate.identifier === authMethodId ||
+        fullAuthMethodId(providerId, candidate) === authMethodId,
+    );
+
+    return method === undefined
+      ? Effect.fail(new AuthMethodNotFoundError({ authMethodId, providerId }))
+      : Effect.succeed(method);
+  };
+
+  const serviceLayer = Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const channels = yield* AgentChannelRuntime.Service;
+      const context = yield* Effect.context<
+        RuntimeRequirementsFor<P> | AuthMethodExecutionRequirementsFor<P | AiProviders[number]>
+      >();
+
+      const appContext = indexGroups(context);
+
+      const provideRuntimeContext = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+        effect.pipe(Effect.updateContext(input => Context.merge(appContext, input)));
+
+      // Requirements are satisfied by the context captured at layer build time;
+      // the cast erases them so service methods expose closed effects.
+      const runWithCapturedAppContext = <A, E>(
+        effect: Effect.Effect<A, E, unknown>,
+      ): Effect.Effect<A, E> => provideRuntimeContext(effect) as never;
+
+      const getAuthMethod = (request: AuthMethodRequest) =>
+        findAuthMethod(request.providerId, request.authMethodId);
+
+      const getTrigger = (request: RuntimeTriggerLifecycleRequest) => {
+        const resolved = resolveRuntimeTrigger(
+          app.plugins,
+          request.triggerId,
+          request.triggerVersion,
+        );
+        return resolved === undefined ||
+          (request.pluginKey !== undefined && resolved.providerId !== request.pluginKey)
+          ? Effect.fail(new TriggerNotFoundError({ triggerId: request.triggerId }))
+          : Effect.succeed(resolved);
+      };
+
+      const triggerLifecycleRequest = (
+        request: RuntimeTriggerLifecycleRequest,
+      ): Trigger.LifecycleRequest => ({
+        config: request.config,
+        ...(request.state === undefined ? {} : { state: request.state }),
+        ...(request.connectionId === undefined ? {} : { connectionId: request.connectionId }),
+        ...(request.context === undefined ? {} : { context: request.context }),
+      });
+
+      const webhookActivationRequest = (
+        request: RuntimeWebhookActivationRequest,
+      ): Trigger.WebhookActivationRequest => ({
+        ...triggerLifecycleRequest(request),
+        webhookUrl: request.webhookUrl,
+      });
+
+      // A host can pass the raw body as text; handlers verify signatures over its bytes.
+      const webhookTriggerLifecycleRequest = (
+        request: RuntimeWebhookTriggerLifecycleRequest,
+      ): Trigger.WebhookExecutionRequest => ({
+        ...webhookActivationRequest(request),
+        request: Predicate.isString(request.request.rawBody)
+          ? { ...request.request, rawBody: new TextEncoder().encode(request.request.rawBody) }
+          : request.request,
+      });
+
+      const activateTrigger = (request: RuntimeWebhookActivationRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const entry = yield* getTrigger(request);
+            return yield* Trigger.activate(entry, webhookActivationRequest(request));
+          }),
+        );
+
+      const deactivateTrigger = (request: RuntimeWebhookActivationRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const entry = yield* getTrigger(request);
+            return yield* Trigger.deactivate(entry, webhookActivationRequest(request));
+          }),
+        );
+
+      const verifyTrigger = (request: RuntimeWebhookTriggerLifecycleRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const entry = yield* getTrigger(request);
+            return yield* Trigger.verify(entry, webhookTriggerLifecycleRequest(request));
+          }),
+        );
+
+      const parseTrigger = (request: RuntimeWebhookTriggerLifecycleRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const entry = yield* getTrigger(request);
+            return yield* Trigger.parse(entry, webhookTriggerLifecycleRequest(request));
+          }),
+        );
+
+      const pollTrigger = (request: RuntimeTriggerLifecycleRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const entry = yield* getTrigger(request);
+            return yield* Trigger.poll(entry, triggerLifecycleRequest(request));
+          }),
+        );
+
+      const decodeAuthMethodSetup = (request: DecodeAuthMethodSetupRequest) =>
+        runWithCapturedAppContext(
+          getAuthMethod(request).pipe(
+            Effect.flatMap(method => {
+              if (request.encoding === "json" && method.setup !== undefined) {
+                return Schema.decodeUnknownEffect(Schema.toCodecJson(method.setup))(request.setup);
+              }
+              return AuthMethodExecution.decodeSetup(method, request.setup);
+            }),
+          ),
+        );
+
+      const withAuthMethodSetup = <A, E, R>(
+        request: DecodeAuthMethodSetupRequest,
+        execute: (
+          method: AuthMethod.Any,
+          setup: AuthMethod.Setup<AuthMethod.Any>,
+        ) => Effect.Effect<A, E, R>,
+      ) =>
+        runWithCapturedAppContext(
+          getAuthMethod(request).pipe(
+            Effect.flatMap(method =>
+              AuthMethodExecution.decodeSetup(method, request.setup).pipe(
+                Effect.flatMap(setup => execute(method, setup)),
+              ),
+            ),
+          ),
+        );
+
+      const prepareAuthMethod = (request: PrepareAuthMethodRequest) =>
+        withAuthMethodSetup(request, (method, setup) =>
+          AuthMethodExecution.prepare(method, request.input, { setup }),
+        );
+
+      const prepareOAuth2Tokens = (request: PrepareOAuth2TokensRequest) =>
+        withAuthMethodSetup(request, (method, setup) =>
+          AuthMethodExecution.prepareOAuth2Tokens(method, request.tokens, { setup }),
+        );
+
+      const refreshAuthMethod = (request: RefreshAuthMethodRequest) =>
+        runWithCapturedAppContext(
+          getAuthMethod(request).pipe(
+            Effect.flatMap(method =>
+              AuthMethodExecution.decodeSetup(method, request.setup).pipe(
+                Effect.flatMap(setup =>
+                  AuthMethodExecution.refreshUnknown(method, request.material, {
+                    minValidityMs: request.minValidityMs,
+                    now: request.now,
+                    reason: request.reason,
+                    setup,
+                  }),
+                ),
+              ),
+            ),
+          ),
+        );
+
+      const resolveAuthMethod = (request: ResolveAuthMethodRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const method = yield* getAuthMethod(request);
+            const setup = yield* decodeAuthMethodSetup(request);
+            const value =
+              request.encoding === "json"
+                ? yield* AuthMethodExecution.resolveDecoded(
+                    method,
+                    yield* Schema.decodeUnknownEffect(Schema.toCodecJson(method.material))(
+                      request.material,
+                    ),
+                    { setup },
+                  )
+                : yield* AuthMethodExecution.resolve(method, request.material, { setup });
+            return AuthMethodBinding.makeBinding({
+              connectionId: undefined,
+              method,
+              providerId: request.providerId,
+              value,
+            });
+          }),
+        );
+
+      const resolveAiModelConfig = (request: ResolveAiModelConfigRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const provider = app.aiProviders.find(
+              candidate => AiProvider.registryId(candidate.identifier) === request.providerId,
+            );
+            if (provider?.resolveRuntimeConfig === undefined) {
+              return yield* new AiProviderRuntimeNotConfiguredError({
+                providerId: request.providerId,
+              });
+            }
+            const binding = yield* resolveAuthMethod(request);
+            // SAFETY: the resolver belongs to this provider and the binding was
+            // resolved from the same provider's declared auth-method list.
+            const resolveRuntimeConfig =
+              provider.resolveRuntimeConfig as AiProvider.RuntimeConfigResolver<
+                readonly AuthMethod.Any[]
+              >;
+            return yield* Schema.decodeUnknownEffect(AiProvider.RuntimeConfig)(
+              resolveRuntimeConfig({ binding, model: request.model }),
+            );
+          }),
+        );
+
+      const resolveSandboxAccess = (request: ResolveAuthMethodRequest) =>
+        runWithCapturedAppContext(
+          Effect.gen(function* () {
+            const access = pluginOf(app, request.providerId)?.sandboxAccess;
+            if (access === undefined) {
+              return yield* new SandboxAccessNotDeclaredError({ providerId: request.providerId });
+            }
+            const context = authRuntimeContext(yield* resolveAuthMethod(request));
+            // Declared origins compare as URL origins, so `https://GHES.example:443` matches requests.
+            const origins = Array.map(
+              access.origins(context),
+              origin => Result.getOrUndefined(Url.fromString(origin))?.origin ?? origin,
+            );
+            const authorize = (outgoing: HttpClientRequest.HttpClientRequest) => {
+              const url = Result.getOrUndefined(Url.fromString(outgoing.url));
+              const refused = new SandboxRequestNotAllowedError({
+                origin: url?.origin ?? outgoing.url,
+                path: url?.pathname ?? "",
+                providerId: request.providerId,
+              });
+              if (url === undefined || !origins.includes(url.origin)) return Effect.fail(refused);
+              return Effect.fromOption(access.authorize(outgoing, context), () => refused);
+            };
+            return { authorize, origins } satisfies ResolvedSandboxAccess;
+          }),
+        );
+
+      return Service.of({
+        activateTrigger,
+        checkAccessAgentChannel: channels.checkAccess,
+        deactivateTrigger,
+        decodeAgentChannelDefinitionSettings: channels.decodeDefinitionSettings,
+        decodeAgentChannelDeploymentSettings: channels.decodeDeploymentSettings,
+        decodeAuthMethodSetup,
+        executeAgentChannel: channels.execute,
+        executeAuthJson: request =>
+          runWithCapturedAppContext(
+            pipe(
+              getAuthMethod(request),
+              Effect.flatMap(method => AuthMethodExecution.executeJson(method, request)),
+            ),
+          ),
+        getAgentChannel: channels.get,
+        getAuthMethod,
+        invoke: request => runWithCapturedAppContext(invokeRaw(app, request)),
+        invokeJson: request =>
+          runWithCapturedAppContext(
+            Effect.gen(function* () {
+              const result = yield* invokeRaw(app, request, true);
+              return {
+                ...result,
+                data: yield* Schema.decodeUnknownEffect(Schema.Json)(result.data),
+              };
+            }),
+          ),
+        parseTrigger,
+        pollTrigger,
+        prepareAuthMethod,
+        prepareOAuth2Tokens,
+        refreshAuthMethod,
+        resolveAiModelConfig,
+        resolveAuthMethod,
+        resolveSandboxAccess,
+        verifyTrigger,
+      });
+    }),
+  );
+
+  return serviceLayer.pipe(
+    Layer.provide(AgentChannelRuntime.layer(app.plugins.map(installation => installation.plugin))),
+    Layer.provide(app.layer),
+  );
+};
+
+export * as DualRuntime from "./DualRuntime.ts";