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

package/src/Plugin.ts

@@ -0,0 +1,912 @@
+/**
+ * Plugin definition builders and types for the Dual SDK.
+ *
+ * A plugin is one integration: its metadata, authentication alternatives, actions, groups,
+ * triggers and Agent Channels, plus the Layer implementing them. A release is the plugin's
+ * package version.
+ *
+ * @since 0.0.0
+ */
+import type { Pipeable, Scope } from "effect";
+import { Array, Effect, Function as Func, Layer, Option, Predicate, Result, String } from "effect";
+
+import type { HttpClientRequest } from "effect/http";
+import { Url, UrlParams } from "effect/http";
+
+import type * as Action from "./Action.ts";
+import * as AgentChannel from "./AgentChannel.ts";
+import type * as AuthMethod from "./AuthMethod.ts";
+import type { ConnectionResolutionContext } from "./ConnectionResolver.ts";
+import type * as Group from "./Group.ts";
+import type { ContextForContract } from "./internal/auth-context.ts";
+import { assertNoDuplicateAuthMethodIdentifiers } from "./internal/auth-runtime.ts";
+import {
+  assertUniqueMixedChildIdentifiers,
+  assertUniqueStructuralChildIdentifiers,
+  type FilterChildren,
+  partitionChildren,
+  type StructuralChildKind,
+} from "./internal/children.ts";
+import { appendElements } from "./internal/collection-utils.ts";
+import { validateIdentifier } from "./internal/identifier.ts";
+import {
+  type HandlerServices as PluginHandlerServices,
+  toHandlers,
+} from "./internal/plugin-handlers.ts";
+import { PipeableProto } from "./internal/proto.ts";
+import type * as Trigger from "./Trigger.ts";
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export const TypeId = "@dual-os/sdk/Plugin" as const;
+
+/**
+ * @since 0.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId;
+
+/** @since 0.0.0 @category models */
+export const categories = [
+  "sales_crm",
+  "marketing",
+  "customer_support",
+  "calendar_scheduling",
+  "communication",
+  "project_management",
+  "developer_tools",
+  "data_storage",
+  "docs_productivity",
+  "commerce_payments",
+  "finance_accounting",
+  "human_resources",
+  "analytics",
+  "design",
+  "it_service_management",
+  "search",
+  "telephony",
+  "web_scraping",
+] as const;
+
+/** @since 0.0.0 @category models */
+export type Category = (typeof categories)[number];
+
+/**
+ * How a command in a run sandbox uses the plugin's Connection over HTTPS without reading its
+ * credential: Dual's sandbox gateway adds the credential to each request that the plugin allows.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface SandboxAccess<
+  Methods extends readonly AuthMethod.Any[] = readonly AuthMethod.Any[],
+> {
+  /** Origins, such as `https://github.com`, that may receive the Connection's credential. */
+  origins(context: Action.HandlerContext<Methods>): readonly string[];
+  /**
+   * Adds the Connection's credential to a request for one of the origins, or refuses the request.
+   * Refuse every request that can read or create a credential, such as a token rotation.
+   */
+  authorize(
+    request: HttpClientRequest.HttpClientRequest,
+    context: Action.HandlerContext<Methods>,
+  ): Option.Option<HttpClientRequest.HttpClientRequest>;
+}
+
+const gitServices = ["git-upload-pack", "git-receive-pack"];
+
+/**
+ * Whether a request is a Git smart HTTP request of a fetch, clone or push: `GET <repository>/info/refs?service=<service>`
+ * or `POST <repository>/<service>` with the service's request content type.
+ *
+ * @since 0.0.0
+ * @category predicates
+ */
+export function isGitRequest(request: HttpClientRequest.HttpClientRequest) {
+  return Result.match(Url.fromString(request.url), {
+    onFailure: () => false,
+    onSuccess: url => {
+      const service = Option.orElse(UrlParams.getFirst(Url.urlParams(url), "service"), () =>
+        UrlParams.getFirst(request.urlParams, "service"),
+      );
+      return Array.some(
+        gitServices,
+        name =>
+          (request.method === "GET" &&
+            String.endsWith("/info/refs")(url.pathname) &&
+            Option.contains(service, name)) ||
+          (request.method === "POST" &&
+            String.endsWith(`/${name}`)(url.pathname) &&
+            request.headers["content-type"] === `application/x-${name}-request`),
+      );
+    },
+  });
+}
+
+/**
+ * Constraint type for working with any {@link Plugin}.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export interface Any extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly authMethods: readonly AuthMethod.Any[];
+  readonly groups: readonly Group.Any[];
+  readonly actions: readonly Action.Any[];
+  readonly triggers: readonly Trigger.Any[];
+  readonly agentChannels: readonly AgentChannel.Any[];
+  readonly sandboxAccess: SandboxAccess | undefined;
+  readonly layer: Layer.Layer<never, any, any>;
+}
+
+/**
+ * A typed plugin definition.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Plugin<
+  out Identifier extends string = string,
+  out AuthMethods extends readonly AuthMethod.Any[] = readonly [],
+  out Groups extends readonly Group.Any[] = readonly [],
+  out Actions extends readonly Action.Any[] = readonly [],
+  out Triggers extends readonly Trigger.Any[] = readonly [],
+  out Channels extends readonly AgentChannel.Any[] = readonly [],
+  LayerOutput = never,
+  out LayerError = never,
+  out LayerRequirements = never,
+>
+  extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: Identifier;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly authMethods: AuthMethods;
+  readonly groups: Groups;
+  readonly actions: Actions;
+  readonly triggers: Triggers;
+  readonly agentChannels: Channels;
+  readonly sandboxAccess: SandboxAccess | undefined;
+  readonly layer: Layer.Layer<LayerOutput, LayerError, LayerRequirements>;
+}
+
+/**
+ * The contract of a plugin without its Layer.
+ *
+ * @since 0.6.0
+ * @category models
+ */
+export type Definition<
+  Identifier extends string,
+  Methods extends readonly AuthMethod.Any[] = readonly [],
+  Groups extends readonly Group.Any[] = readonly [],
+  Actions extends readonly Action.Any[] = readonly [],
+  Triggers extends readonly Trigger.Any[] = readonly [],
+  Channels extends readonly AgentChannel.Any[] = readonly [],
+> = Plugin<Identifier, Methods, Groups, Actions, Triggers, Channels>;
+
+/**
+ * A plugin contract with the services its Layer provides.
+ *
+ * @since 0.7.0
+ * @category models
+ */
+export type Provided<
+  P extends Any,
+  LayerOutput,
+  LayerError = never,
+  LayerRequirements = never,
+> = Plugin<
+  P["identifier"],
+  P["authMethods"],
+  P["groups"],
+  P["actions"],
+  P["triggers"],
+  P["agentChannels"],
+  LayerOutput,
+  LayerError,
+  LayerRequirements
+>;
+
+/**
+ * Runtime services produced by plugin layers.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type LayerOutput<Plugins extends readonly Any[]> =
+  Plugins[number] extends Plugin<any, any, any, any, any, any, infer Output, any, any>
+    ? Output
+    : never;
+
+/**
+ * Errors surfaced while constructing plugin layers.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type LayerError<Plugins extends readonly Any[]> =
+  Plugins[number] extends Plugin<any, any, any, any, any, any, any, infer Error, any>
+    ? Error
+    : never;
+
+/**
+ * Runtime services required by plugin layers.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type LayerRequirements<Plugins extends readonly Any[]> =
+  Plugins[number] extends Plugin<any, any, any, any, any, any, any, any, infer Requirements>
+    ? Requirements
+    : never;
+
+/** @since 0.0.0 @category type-level */
+export type StructuralChild = Group.Any | Action.Any | Trigger.Any;
+
+/** @since 0.0.0 @category type-level */
+export type GroupsFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Group.Any
+>;
+
+/** @since 0.0.0 @category type-level */
+export type ActionsFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Action.Any
+>;
+
+/** @since 0.0.0 @category type-level */
+export type TriggersFromChildren<Children extends readonly StructuralChild[]> = FilterChildren<
+  Children,
+  Trigger.Any
+>;
+
+/**
+ * Result of appending capabilities to a plugin.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type AddChildren<
+  P extends Any,
+  AddedGroups extends readonly Group.Any[] = readonly [],
+  AddedActions extends readonly Action.Any[] = readonly [],
+  AddedTriggers extends readonly Trigger.Any[] = readonly [],
+  AddedChannels extends readonly AgentChannel.Any[] = readonly [],
+> =
+  P extends Plugin<
+    infer Identifier,
+    infer Methods,
+    infer Groups,
+    infer Actions,
+    infer Triggers,
+    infer Channels,
+    infer Output,
+    infer Error,
+    infer Requirements
+  >
+    ? Plugin<
+        Identifier,
+        Methods,
+        readonly [...Groups, ...AddedGroups],
+        readonly [...Actions, ...AddedActions],
+        readonly [...Triggers, ...AddedTriggers],
+        readonly [...Channels, ...AddedChannels],
+        Output,
+        Error,
+        Requirements
+      >
+    : never;
+
+/**
+ * Result of appending auth methods to a plugin.
+ *
+ * @since 0.0.0
+ * @category type-level
+ */
+export type AddAuthMethods<P extends Any, AddedMethods extends readonly AuthMethod.Any[]> =
+  P extends Plugin<
+    infer Identifier,
+    infer Methods,
+    infer Groups,
+    infer Actions,
+    infer Triggers,
+    infer Channels,
+    infer Output,
+    infer Error,
+    infer Requirements
+  >
+    ? Plugin<
+        Identifier,
+        readonly [...Methods, ...AddedMethods],
+        Groups,
+        Actions,
+        Triggers,
+        Channels,
+        Output,
+        Error,
+        Requirements
+      >
+    : never;
+
+interface Fields {
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly authMethods: readonly AuthMethod.Any[];
+  readonly groups: readonly Group.Any[];
+  readonly actions: readonly Action.Any[];
+  readonly triggers: readonly Trigger.Any[];
+  readonly agentChannels: readonly AgentChannel.Any[];
+  readonly sandboxAccess: SandboxAccess | undefined;
+  readonly layer: Layer.Layer<never, any, any>;
+}
+
+const Proto = { ...PipeableProto, [TypeId]: TypeId };
+
+const makePlugin = (fields: Fields): Any => {
+  validateIdentifier("plugin", fields.identifier);
+  assertNoDuplicateAuthMethodIdentifiers(fields.identifier, fields.authMethods);
+  return Object.assign(Object.create(Proto), fields);
+};
+
+const update = (plugin: Any, fields: Partial<Fields>): Any => makePlugin({ ...plugin, ...fields });
+
+/**
+ * Create an empty {@link Plugin}.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export const make = <const Identifier extends string>(identifier: Identifier): Plugin<Identifier> =>
+  makePlugin({
+    actions: [],
+    agentChannels: [],
+    authMethods: [],
+    categories: [],
+    description: undefined,
+    docsUrl: undefined,
+    groups: [],
+    homepageUrl: undefined,
+    iconUrl: undefined,
+    iconUrlDark: undefined,
+    identifier,
+    layer: Layer.empty,
+    name: undefined,
+    sandboxAccess: undefined,
+    triggers: [],
+  }) as never;
+
+/**
+ * Check if a value is a {@link Plugin}.
+ *
+ * @since 0.0.0
+ * @category guards
+ */
+export const isPlugin = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId);
+
+const metadata = <
+  Key extends "name" | "description" | "iconUrl" | "iconUrlDark" | "homepageUrl" | "docsUrl",
+>(
+  key: Key,
+): {
+  (value: string): <P extends Any>(plugin: P) => P;
+  <P extends Any>(plugin: P, value: string): P;
+} => Func.dual(2, (plugin: Any, value: string) => update(plugin, { [key]: value })) as never;
+
+/** @since 0.0.0 @category combinators */
+export const withName = metadata("name");
+/** @since 0.0.0 @category combinators */
+export const withDescription = metadata("description");
+/** @since 0.6.0 @category combinators */
+export const withIconUrl = metadata("iconUrl");
+/** @since 0.6.0 @category combinators */
+export const withIconUrlDark = metadata("iconUrlDark");
+/** @since 0.6.0 @category combinators */
+export const withHomepageUrl = metadata("homepageUrl");
+/** @since 0.6.0 @category combinators */
+export const withDocsUrl = metadata("docsUrl");
+
+/** @since 0.6.0 @category combinators */
+export const withCategories: {
+  (categories: readonly Category[]): <P extends Any>(plugin: P) => P;
+  <P extends Any>(plugin: P, categories: readonly Category[]): P;
+} = Func.dual(2, (plugin: Any, categories: readonly Category[]) =>
+  update(plugin, { categories: [...categories] }),
+);
+
+/**
+ * Add authentication alternatives. Actions and triggers accept every method.
+ *
+ * @since 0.6.0
+ * @category combinators
+ */
+export const withAuthMethods =
+  <const Methods extends readonly AuthMethod.Any[]>(methods: Methods) =>
+  <P extends Any>(plugin: P): AddAuthMethods<P, Methods> => {
+    if (plugin.sandboxAccess !== undefined) {
+      throw new Error(
+        `plugin "${plugin.identifier}" must declare auth methods before its sandbox access`,
+      );
+    }
+    return update(plugin, { authMethods: appendElements(plugin.authMethods, methods) }) as never;
+  };
+
+/**
+ * Add an authentication alternative. Actions and triggers accept every method.
+ *
+ * @since 0.6.0
+ * @category combinators
+ */
+export const withAuthMethod: {
+  <const Method extends AuthMethod.Any>(
+    method: Method,
+  ): <P extends Any>(plugin: P) => AddAuthMethods<P, readonly [Method]>;
+  <P extends Any, const Method extends AuthMethod.Any>(
+    plugin: P,
+    method: Method,
+  ): AddAuthMethods<P, readonly [Method]>;
+} = Func.dual(2, (plugin: Any, method: AuthMethod.Any) => withAuthMethods([method])(plugin));
+
+/**
+ * Lets commands in a run sandbox use the plugin's Connection through Dual's sandbox gateway.
+ *
+ * @since 0.6.0
+ * @category combinators
+ */
+export const withSandboxAccess =
+  <Methods extends readonly AuthMethod.Any[]>(access: SandboxAccess<Methods>) =>
+  <P extends Any>(plugin: P & { readonly authMethods: Methods }): P =>
+    update(plugin, { sandboxAccess: access as SandboxAccess }) as P;
+
+const appendChildren = (
+  plugin: Any,
+  children: readonly StructuralChild[],
+  childKind?: StructuralChildKind,
+): Any => {
+  if (childKind === undefined) {
+    assertUniqueMixedChildIdentifiers("plugin", plugin.identifier, plugin, children);
+  } else {
+    assertUniqueStructuralChildIdentifiers(
+      "plugin",
+      plugin.identifier,
+      plugin,
+      children,
+      childKind,
+    );
+  }
+  const partitioned = partitionChildren(children);
+  return update(plugin, {
+    actions: appendElements(plugin.actions, partitioned.actions),
+    groups: appendElements(plugin.groups, partitioned.groups),
+    triggers: appendElements(plugin.triggers, partitioned.triggers),
+  });
+};
+
+/** @since 0.6.0 @category combinators */
+export const withAction: {
+  <const Added extends Action.Any>(
+    action: Added,
+  ): <P extends Any>(plugin: P) => AddChildren<P, readonly [], readonly [Added]>;
+  <P extends Any, const Added extends Action.Any>(
+    plugin: P,
+    action: Added,
+  ): AddChildren<P, readonly [], readonly [Added]>;
+} = Func.dual(2, (plugin: Any, action: Action.Any) => appendChildren(plugin, [action], "action"));
+
+/** @since 0.6.0 @category combinators */
+export const withGroup: {
+  <const Added extends Group.Any>(
+    group: Added,
+  ): <P extends Any>(plugin: P) => AddChildren<P, readonly [Added]>;
+  <P extends Any, const Added extends Group.Any>(
+    plugin: P,
+    group: Added,
+  ): AddChildren<P, readonly [Added]>;
+} = Func.dual(2, (plugin: Any, group: Group.Any) => appendChildren(plugin, [group], "group"));
+
+/** @since 0.6.0 @category combinators */
+export const withTrigger: {
+  <const Added extends Trigger.Any>(
+    trigger: Added,
+  ): <P extends Any>(plugin: P) => AddChildren<P, readonly [], readonly [], readonly [Added]>;
+  <P extends Any, const Added extends Trigger.Any>(
+    plugin: P,
+    trigger: Added,
+  ): AddChildren<P, readonly [], readonly [], readonly [Added]>;
+} = Func.dual(2, (plugin: Any, trigger: Trigger.Any) =>
+  appendChildren(plugin, [trigger], "trigger"),
+);
+
+/** Add the generated action groups. @since 0.6.0 @category combinators */
+export const withGroups =
+  <const Groups extends readonly Group.Any[]>(groups: Groups) =>
+  <P extends Any>(plugin: P): AddChildren<P, Groups> =>
+    appendChildren(plugin, groups, "group") as never;
+
+/** Add trigger definitions from an overlay. @since 0.6.0 @category combinators */
+export const withTriggers =
+  <const Triggers extends readonly Trigger.Any[]>(triggers: Triggers) =>
+  <P extends Any>(plugin: P): AddChildren<P, readonly [], readonly [], Triggers> =>
+    appendChildren(plugin, triggers, "trigger") as never;
+
+/** Add grouped capabilities. @since 0.6.0 @category combinators */
+export const add =
+  <const Children extends readonly StructuralChild[]>(...children: Children) =>
+  <P extends Any>(
+    plugin: P,
+  ): AddChildren<
+    P,
+    GroupsFromChildren<Children>,
+    ActionsFromChildren<Children>,
+    TriggersFromChildren<Children>
+  > =>
+    appendChildren(plugin, children) as never;
+
+/** Add an Agent Channel; its definition owns its exact auth subset. @since 0.6.0 @category combinators */
+export const withAgentChannel =
+  <const Channel extends AgentChannel.Any>(channel: Channel) =>
+  <P extends Any>(
+    plugin: P,
+  ): AddChildren<P, readonly [], readonly [], readonly [], readonly [Channel]> => {
+    if (
+      [...plugin.actions, ...plugin.triggers, ...plugin.groups, ...plugin.agentChannels].some(
+        child => child.identifier === channel.identifier,
+      )
+    ) {
+      throw new AgentChannel.ChannelError({ code: "invalid_definition" });
+    }
+    AgentChannel.validateDefinition(channel.definition, plugin.identifier, plugin.authMethods);
+    return update(plugin, { agentChannels: [...plugin.agentChannels, channel] }) as never;
+  };
+
+/**
+ * Attach runtime services to a plugin definition.
+ *
+ * @since 0.0.0
+ * @category combinators
+ */
+export const provide: {
+  <AddedOutput, AddedError, AddedRequirements>(
+    layer: Layer.Layer<AddedOutput, AddedError, AddedRequirements>,
+  ): <P extends Any>(
+    plugin: P,
+  ) => Provided<
+    P,
+    LayerOutput<readonly [P]> | AddedOutput,
+    LayerError<readonly [P]> | AddedError,
+    AddedRequirements | Exclude<LayerRequirements<readonly [P]>, AddedOutput>
+  >;
+  <P extends Any, AddedOutput, AddedError, AddedRequirements>(
+    plugin: P,
+    layer: Layer.Layer<AddedOutput, AddedError, AddedRequirements>,
+  ): Provided<
+    P,
+    LayerOutput<readonly [P]> | AddedOutput,
+    LayerError<readonly [P]> | AddedError,
+    AddedRequirements | Exclude<LayerRequirements<readonly [P]>, AddedOutput>
+  >;
+} = Func.dual(2, (plugin: Any, layer: Layer.Layer<never, any, any>) =>
+  update(plugin, { layer: Layer.provideMerge(plugin.layer, layer) }),
+);
+
+/** Runtime handler services contributed by a plugin. @since 0.6.0 @category type-level */
+export type HandlerServices<P extends Any> = PluginHandlerServices<P>;
+
+/** The service carrying a plugin's action handlers. @since 0.7.0 @category type-level */
+export type { ActionHandlerService, ActionHandlerServiceOf } from "./internal/plugin-handlers.ts";
+
+interface Node {
+  readonly actions: readonly Action.Any[];
+  readonly groups: readonly Group.Any[];
+  readonly triggers: readonly Trigger.Any[];
+  readonly agentChannels?: readonly AgentChannel.Any[];
+}
+
+type ActionName<N extends Node> = N["actions"][number]["identifier"];
+type GroupName<N extends Node> = N["groups"][number]["identifier"];
+type TriggerName<N extends Node> = N["triggers"][number]["identifier"];
+
+type ActionNamed<N extends Node, Name> = Extract<
+  N["actions"][number],
+  { readonly identifier: Name }
+>;
+type GroupNamed<N extends Node, Name> = Extract<N["groups"][number], { readonly identifier: Name }>;
+type TriggerNamed<N extends Node, Name> = Extract<
+  N["triggers"][number],
+  { readonly identifier: Name }
+>;
+
+type Channels<N extends Node> = N extends {
+  readonly agentChannels: infer C extends readonly AgentChannel.Any[];
+}
+  ? C[number]
+  : never;
+type ChannelName<N extends Node> = Channels<N>["identifier"];
+type ChannelNamed<N extends Node, Name> = Extract<Channels<N>, { readonly identifier: Name }>;
+type Names<N extends Node> = ActionName<N> | GroupName<N> | TriggerName<N> | ChannelName<N>;
+
+// Concrete parameter types, not a generic handler, let `Effect.fn` infer its arguments.
+type ActionHandler<A extends Action.Any, Methods extends readonly AuthMethod.Any[], R> = (
+  input: Action.Input<A>,
+  context: ContextForContract<Methods, A["requireAuth"]>,
+) => Effect.Effect<Action.Output<A>, Action.ActionHandlerFailure, R>;
+
+type TriggerContext<
+  T extends Trigger.Any,
+  Methods extends readonly AuthMethod.Any[],
+> = ContextForContract<Methods, T["requireAuth"]> & ConnectionResolutionContext;
+
+type Emit<T extends Trigger.Any> = Trigger.EmitResult<Trigger.Output<T>, Trigger.State<T>>;
+
+type WebhookInput<T extends Trigger.Any> = Trigger.WebhookLifecycleInput<
+  Trigger.Config<T>,
+  Trigger.State<T>
+>;
+type ActivationInput<T extends Trigger.Any> = Trigger.WebhookActivationInput<
+  Trigger.Config<T>,
+  Trigger.State<T>
+>;
+
+/** Lifecycle handlers each trigger kind must implement; each hook infers its own requirements. */
+type TriggerLifecycle<
+  T extends Trigger.Any,
+  Methods extends readonly AuthMethod.Any[],
+  RActivate,
+  RDeactivate,
+  RVerify,
+  REmit,
+> = T["kind"] extends "webhook"
+  ? {
+      readonly activate?: (
+        input: ActivationInput<T>,
+        context: TriggerContext<T, Methods>,
+      ) => Effect.Effect<Trigger.ActivationResult<Trigger.State<T>>, unknown, RActivate>;
+      readonly deactivate?: (
+        input: ActivationInput<T>,
+        context: TriggerContext<T, Methods>,
+      ) => Effect.Effect<void, unknown, RDeactivate>;
+      readonly verify?: (
+        input: WebhookInput<T>,
+        context: TriggerContext<T, Methods>,
+      ) => Effect.Effect<void | Trigger.VerifyResult<Trigger.State<T>>, unknown, RVerify>;
+      readonly parse: (
+        input: WebhookInput<T>,
+        context: TriggerContext<T, Methods>,
+      ) => Effect.Effect<Emit<T>, unknown, REmit>;
+    }
+  : {
+      readonly poll: (
+        input: Trigger.PollingInput<Trigger.Config<T>, Trigger.State<T>>,
+        context: TriggerContext<T, Methods>,
+      ) => Effect.Effect<Emit<T>, unknown, REmit>;
+    };
+
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (
+  value: infer I,
+) => void
+  ? I
+  : never;
+
+/** Typed lifecycles exported by a trigger overlay. @since 0.6.0 @category handlers */
+export type TriggerHandlers<
+  Triggers extends readonly Trigger.Any[],
+  Methods extends readonly AuthMethod.Any[],
+> = {
+  readonly [T in Triggers[number] as T["identifier"]]: TriggerLifecycle<
+    T,
+    Methods,
+    any,
+    any,
+    any,
+    any
+  >;
+};
+
+type LifecycleRequirements<H> = H extends (...args: any[]) => Effect.Effect<any, any, infer R>
+  ? R
+  : H extends object
+    ? { [K in keyof H]: LifecycleRequirements<H[K]> }[keyof H]
+    : never;
+
+/** Rejects a union of names, which would mark several capabilities handled by one handler. */
+type Single<Name> = [Name] extends [UnionToIntersection<Name>] ? unknown : never;
+
+/**
+ * Immutable handler collection for one plugin or group. Each registration
+ * removes its name from the names still accepted.
+ *
+ * @since 0.6.0
+ * @category handlers
+ */
+export interface HandlerCollection<
+  N extends Node,
+  Methods extends readonly AuthMethod.Any[],
+  Handled extends PropertyKey = never,
+  R = never,
+> {
+  readonly "~node": N;
+  readonly "~handled": Handled;
+  readonly "~requirements": R;
+  /** @internal */
+  readonly actions: Readonly<Record<string, unknown>>;
+  /** @internal */
+  readonly triggers: Readonly<Record<string, unknown>>;
+  readonly agentChannels: Readonly<Record<string, unknown>>;
+
+  /** Implement a Channel declared by the plugin. */
+  channel<const Name extends Exclude<ChannelName<N>, Handled>, R1>(
+    name: Name & Single<Name>,
+    lifecycle: AgentChannel.RuntimeContract<ChannelNamed<N, Name>["definition"], R1>,
+  ): HandlerCollection<N, Methods, Handled | Name, R | R1>;
+
+  /** Register the lifecycles from a typed trigger overlay. */
+  withTriggers<H extends TriggerHandlers<N["triggers"], Methods>>(
+    lifecycles: H &
+      Record<Exclude<keyof H, TriggerName<N>>, never> &
+      ([Extract<Handled, TriggerName<N>>] extends [never] ? unknown : never),
+  ): HandlerCollection<N, Methods, Handled | TriggerName<N>, R | LifecycleRequirements<H>>;
+
+  /** Implement an action declared directly on this plugin or group. */
+  action<const Name extends Exclude<ActionName<N>, Handled>, R1>(
+    name: Name & Single<Name>,
+    handler: ActionHandler<ActionNamed<N, Name>, Methods, R1>,
+  ): HandlerCollection<N, Methods, Handled | Name, R | R1>;
+
+  /** Implement every capability of a nested group. */
+  group<const Name extends Exclude<GroupName<N>, Handled>, Return>(
+    name: Name & Single<Name>,
+    build: (
+      handlers: HandlerCollection<GroupNamed<N, Name>, Methods>,
+    ) => ValidateHandlers<Return, GroupNamed<N, Name>>,
+  ): HandlerCollection<N, Methods, Handled | Name, R | Requirements<Return>>;
+
+  /** Implement the lifecycle of a trigger declared directly on this plugin or group. */
+  trigger<
+    const Name extends Exclude<TriggerName<N>, Handled>,
+    RActivate = never,
+    RDeactivate = never,
+    RVerify = never,
+    REmit = never,
+  >(
+    name: Name & Single<Name>,
+    lifecycle: TriggerLifecycle<
+      TriggerNamed<N, Name>,
+      Methods,
+      RActivate,
+      RDeactivate,
+      RVerify,
+      REmit
+    >,
+  ): HandlerCollection<N, Methods, Handled | Name, R | RActivate | RDeactivate | RVerify | REmit>;
+}
+
+type Built<Return> = Return extends Effect.Effect<infer H, any, any> ? H : Return;
+
+/** Accept the expected node's handler collection once every capability is implemented. */
+type ValidateHandlers<H, N extends Node> =
+  H extends HandlerCollection<N, any, infer Handled, any>
+    ? [Exclude<Names<N>, Handled>] extends [never]
+      ? H
+      : `Capability not handled: ${Exclude<Names<N>, Handled> & string}`
+    : "Must return the handlers of this plugin or group";
+
+/**
+ * Accept the plugin's handlers, or an Effect building them, once every
+ * declared capability is implemented.
+ *
+ * @since 0.6.0
+ * @category type-level
+ */
+export type ValidateReturn<Return, N extends Node> = [ValidateHandlers<Built<Return>, N>] extends [
+  HandlerCollection<any, any, any, any>,
+]
+  ? Return
+  : ValidateHandlers<Built<Return>, N>;
+
+/**
+ * Services the handlers need, including those needed to build them.
+ *
+ * @since 0.6.0
+ * @category type-level
+ */
+export type Requirements<Return> =
+  Return extends Effect.Effect<HandlerCollection<any, any, any, infer R>, any, infer RX>
+    ? R | RX
+    : Return extends HandlerCollection<any, any, any, infer R>
+      ? R
+      : never;
+
+/**
+ * Failures raised while building the handlers.
+ *
+ * @since 0.6.0
+ * @category type-level
+ */
+export type BuildError<Return> = Return extends Effect.Effect<any, infer E, any> ? E : never;
+
+const makeHandlers = (
+  actions: Readonly<Record<string, unknown>>,
+  triggers: Readonly<Record<string, unknown>>,
+  agentChannels: Readonly<Record<string, unknown>> = {},
+): HandlerCollection<any, any> =>
+  ({
+    action: (name: string, handler: unknown) =>
+      makeHandlers({ ...actions, [name]: handler }, triggers, agentChannels),
+    actions,
+    agentChannels,
+    channel: (name: string, lifecycle: unknown) =>
+      makeHandlers(actions, triggers, { ...agentChannels, [name]: lifecycle }),
+    group: (
+      name: string,
+      build: (handlers: HandlerCollection<any, any>) => HandlerCollection<any, any>,
+    ) => {
+      const group = build(makeHandlers({}, {}));
+      return makeHandlers(
+        { ...actions, [name]: group.actions },
+        { ...triggers, [name]: group.triggers },
+        agentChannels,
+      );
+    },
+    trigger: (name: string, lifecycle: unknown) =>
+      makeHandlers(actions, { ...triggers, [name]: lifecycle }, agentChannels),
+    triggers,
+    withTriggers: (lifecycles: Readonly<Record<string, unknown>>) =>
+      makeHandlers(actions, { ...triggers, ...lifecycles }, agentChannels),
+  }) as never;
+
+/**
+ * Handler collection passed to {@link toLayer}.
+ *
+ * @since 0.6.0
+ * @category handlers
+ */
+export type Handlers<P extends Any> = HandlerCollection<P, P["authMethods"]>;
+
+/**
+ * Implement a plugin's capabilities. `build` registers one handler per action,
+ * trigger and Channel; the Layer is rejected until every capability is implemented.
+ *
+ * @since 0.6.0
+ * @category handlers
+ */
+export const toLayer = <P extends Any, Return>(
+  plugin: P,
+  build: (handlers: Handlers<P>) => ValidateReturn<Return, P>,
+): Layer.Layer<
+  HandlerServices<P>,
+  BuildError<Return>,
+  Exclude<Requirements<Return>, Scope.Scope>
+> =>
+  Layer.effectContext(
+    Effect.gen(function* () {
+      const result = build(makeHandlers({}, {})) as unknown;
+      const handlers = (Effect.isEffect(result) ? yield* result : result) as HandlerCollection<
+        any,
+        any
+      >;
+      return yield* toHandlers(plugin, handlers);
+    }),
+  ) as never;