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

package/src/internal/dual/registry.ts

@@ -0,0 +1,340 @@
+/** Materialized Dual registry DTOs and resolver. */
+import { Schema } from "effect";
+
+import * as AgentChannel from "../../AgentChannel.ts";
+import * as AiProvider from "../../AiProvider.ts";
+import type * as AuthMethod from "../../AuthMethod.ts";
+import type { PluginInstallation } from "../../DualRuntime.ts";
+import type * as Plugin from "../../Plugin.ts";
+
+import { collectActionEntries } from "./actions.ts";
+import { collectTriggerEntries } from "./triggers.ts";
+
+export interface MaterializedRegistryOptions {
+  readonly schemaJson?: ((schema: Schema.Top) => unknown) | undefined;
+  readonly projections?: Map<Schema.Top, unknown> | undefined;
+  /** Selects the capability versions whose schemas are projected; the others carry `undefined` schemas. */
+  readonly projectSchemas?: ((capabilityId: string, version: string) => boolean) | undefined;
+}
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedAuthMethod {
+  readonly id: string;
+  readonly providerId: string;
+  readonly key: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly kind: AuthMethod.AuthMethodKind;
+  readonly setupSchemaJson: unknown | null;
+  readonly inputSchemaJson: unknown | null;
+  readonly materialSchemaJson: unknown;
+  readonly metadataJson: unknown;
+}
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedProvider {
+  readonly kind: "tools" | "ai";
+  readonly id: string;
+  readonly key: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly iconUrl: string | undefined;
+  readonly iconUrlDark: string | undefined;
+  readonly categories: readonly Plugin.Category[];
+  readonly homepageUrl: string | undefined;
+  readonly docsUrl: string | undefined;
+  /** Whether a shell in a run sandbox may use the provider's Connections through Dual's gateway. */
+  readonly sandboxAccess: boolean;
+  readonly sourcePluginKey: string | undefined;
+  readonly sourcePluginVersion: string | undefined;
+  readonly authMethods: readonly MaterializedAuthMethod[];
+  readonly capabilityVersions: readonly MaterializedCapabilityVersion[];
+}
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedActionCapabilityVersion {
+  readonly kind: "action";
+  readonly requireAuth: boolean;
+  readonly capabilityId: string;
+  readonly key: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly version: string;
+  readonly sourcePluginKey: string | undefined;
+  readonly sourcePluginVersion: string | undefined;
+  readonly authMethodIds: readonly string[];
+  readonly inputSchemaJson: unknown;
+  readonly outputSchemaJson: unknown;
+  readonly examplesJson: unknown;
+}
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedTriggerCapabilityVersion {
+  readonly kind: "trigger";
+  readonly requireAuth: boolean;
+  readonly capabilityId: string;
+  readonly key: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly version: string;
+  readonly sourcePluginKey: string | undefined;
+  readonly sourcePluginVersion: string | undefined;
+  readonly authMethodIds: readonly string[];
+  readonly triggerKind: "webhook" | "polling";
+  readonly configSchemaJson: unknown;
+  readonly outputSchemaJson: unknown;
+  readonly stateSchemaJson: unknown | undefined;
+}
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedChannelCapabilityVersion {
+  readonly kind: "agent_channel";
+  readonly requireAuth: boolean;
+  readonly capabilityId: string;
+  readonly key: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly version: string;
+  readonly sourcePluginKey: string | undefined;
+  readonly sourcePluginVersion: string | undefined;
+  readonly authMethodIds: readonly string[];
+  readonly definitionSettingsSchemaJson: unknown;
+  readonly deploymentSettingsSchemaJson: unknown;
+  readonly stateSchemaJson: unknown;
+  readonly operationInputSchemaJson: unknown;
+  readonly operationOutputSchemaJson: unknown;
+  readonly extensionsSchemaJson: Readonly<Record<string, unknown>>;
+  readonly featuresJson: AgentChannel.Features;
+  readonly exposure: typeof AgentChannel.Exposure.Type;
+  /** Absent for the original protocol. */
+  readonly protocol?: AgentChannel.Protocol;
+  readonly requiredChecks: typeof AgentChannel.RequiredChecks.Type;
+}
+export type MaterializedCapabilityVersion =
+  | MaterializedChannelCapabilityVersion
+  | MaterializedActionCapabilityVersion
+  | MaterializedTriggerCapabilityVersion;
+
+/** @since 0.0.0 @category registry */
+export interface MaterializedRegistry {
+  readonly dualIdentifier: string;
+  readonly providers: readonly MaterializedProvider[];
+}
+
+const authMethodId = (providerId: string, methodId: string): string => `${providerId}/${methodId}`;
+
+// FIXME(live-schema-validation): this JSON Schema is a lossy catalog/snapshot projection.
+// Hard validation must use the live SDK Schema declarations for the pinned version.
+const schemaJson = (schema: Schema.Top): unknown =>
+  Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" });
+
+const authMethodMetadataJson = (method: AuthMethod.Any): unknown => {
+  if (method.oauth2 === undefined) {
+    return {};
+  }
+
+  const staticClient =
+    typeof method.oauth2.client === "function" ? undefined : method.oauth2.client;
+
+  // An endpoint derived from the setup has no value until a connection supplies
+  // one, so the registry — which describes the method, not a connection — omits
+  // it, exactly as it already omits a client built by a hook.
+  const staticEndpoint = (endpoint: string | ((...args: never) => string) | undefined) =>
+    typeof endpoint === "function" ? undefined : endpoint;
+  const discoveryUrl = staticEndpoint(method.oauth2.discoveryUrl);
+  const authorizationUrl = staticEndpoint(method.oauth2.authorizationUrl);
+  const tokenUrl = staticEndpoint(method.oauth2.tokenUrl);
+
+  return {
+    oauth2: {
+      scopes: method.oauth2.scopes,
+      ...(staticClient === undefined
+        ? {}
+        : { clientAuthentication: staticClient.authentication ?? "basic" }),
+      ...(discoveryUrl === undefined ? {} : { discoveryUrl }),
+      ...(authorizationUrl === undefined ? {} : { authorizationUrl }),
+      ...(tokenUrl === undefined ? {} : { tokenUrl }),
+      ...(method.oauth2.pkce === undefined ? {} : { pkce: method.oauth2.pkce }),
+      ...(method.oauth2.authorizationParams === undefined
+        ? {}
+        : { authorizationParams: method.oauth2.authorizationParams }),
+      ...(method.oauth2.tokenParams === undefined
+        ? {}
+        : { tokenParams: method.oauth2.tokenParams }),
+    },
+  };
+};
+
+/**
+ * Materialize the provider/capability registry of the installed plugin releases. This is the
+ * canonical SDK-owned resolver used by server persistence/bootstrap code.
+ *
+ * @since 0.0.0
+ * @category registry
+ */
+export const materializeResolvedRegistry = (input: {
+  readonly dualIdentifier: string;
+  readonly plugins: readonly PluginInstallation[];
+  readonly aiProviders: readonly AiProvider.Any[];
+  readonly schemaJson?: ((schema: Schema.Top) => unknown) | undefined;
+  readonly projections?: Map<Schema.Top, unknown> | undefined;
+  readonly projectSchemas?: ((capabilityId: string, version: string) => boolean) | undefined;
+}): MaterializedRegistry => {
+  // Plugins reuse schema values across capabilities, auth methods and app
+  // versions, so project each one once per materialization. The memo is dropped
+  // with the caller's materialization rather than retaining every projection for
+  // the lifetime of the app definition.
+  const projectedSchemas = input.projections ?? new Map<Schema.Top, unknown>();
+  const projectSchemaUncached = input.schemaJson ?? schemaJson;
+  const projectSchema = (schema: Schema.Top): unknown => {
+    if (projectedSchemas.has(schema)) return projectedSchemas.get(schema);
+    const projected = projectSchemaUncached(schema);
+    projectedSchemas.set(schema, projected);
+    return projected;
+  };
+  const projectSchemasFor = input.projectSchemas ?? (() => true);
+  const capabilityVersionsByProvider = new Map<string, MaterializedCapabilityVersion[]>();
+  const addCapabilityVersion = (
+    providerId: string,
+    capabilityVersion: MaterializedCapabilityVersion,
+  ) => {
+    const versions = capabilityVersionsByProvider.get(providerId) ?? [];
+    versions.push(capabilityVersion);
+    capabilityVersionsByProvider.set(providerId, versions);
+  };
+
+  for (const entry of collectActionEntries(input.plugins)) {
+    const projected = projectSchemasFor(entry.actionId, entry.pluginVersion);
+    addCapabilityVersion(entry.providerId, {
+      authMethodIds: entry.authMethods.map(method =>
+        authMethodId(entry.providerId, method.identifier),
+      ),
+      capabilityId: entry.actionId,
+      description: entry.action.description,
+      examplesJson: entry.action.examples,
+      inputSchemaJson: projected ? projectSchema(entry.action.input) : undefined,
+      key: entry.localId,
+      kind: "action" as const,
+      requireAuth: entry.action.requireAuth !== false,
+      name: entry.action.name,
+      outputSchemaJson: projected ? projectSchema(entry.action.output) : undefined,
+      sourcePluginKey: entry.providerId,
+      sourcePluginVersion: entry.pluginVersion,
+      version: entry.pluginVersion,
+    });
+  }
+
+  for (const entry of collectTriggerEntries(input.plugins)) {
+    const projected = projectSchemasFor(entry.triggerId, entry.pluginVersion);
+    addCapabilityVersion(entry.providerId, {
+      authMethodIds: entry.authMethods.map(method =>
+        authMethodId(entry.providerId, method.identifier),
+      ),
+      capabilityId: entry.triggerId,
+      configSchemaJson: projected ? projectSchema(entry.trigger.config) : undefined,
+      description: entry.trigger.description,
+      key: entry.localId,
+      kind: "trigger" as const,
+      requireAuth: entry.trigger.requireAuth !== false,
+      name: entry.trigger.name,
+      outputSchemaJson: projected ? projectSchema(entry.trigger.output) : undefined,
+      sourcePluginKey: entry.providerId,
+      sourcePluginVersion: entry.pluginVersion,
+      stateSchemaJson:
+        projected && entry.trigger.state !== undefined
+          ? projectSchema(entry.trigger.state)
+          : undefined,
+      triggerKind: entry.trigger.kind,
+      version: entry.pluginVersion,
+    });
+  }
+
+  for (const { plugin, version } of input.plugins) {
+    for (const channel of plugin.agentChannels) {
+      const definition = channel.definition;
+      AgentChannel.validateDefinition(definition, plugin.identifier, plugin.authMethods);
+      addCapabilityVersion(plugin.identifier, {
+        authMethodIds: definition.authMethods.map(method =>
+          authMethodId(plugin.identifier, method.identifier),
+        ),
+        capabilityId: `${plugin.identifier}/${channel.identifier}`,
+        description: channel.description,
+        key: channel.identifier,
+        kind: "agent_channel",
+        requireAuth: true,
+        name: channel.name,
+        sourcePluginKey: plugin.identifier,
+        sourcePluginVersion: version,
+        version,
+        ...AgentChannel.projectContract(definition, projectSchema),
+      });
+    }
+  }
+  const toolProviders: readonly MaterializedProvider[] = input.plugins.map(
+    ({ plugin, version }) => ({
+      authMethods: plugin.authMethods.map(method => ({
+        description: method.description,
+        id: authMethodId(plugin.identifier, method.identifier),
+        inputSchemaJson: method.input === undefined ? null : projectSchema(method.input),
+        key: method.identifier,
+        kind: method.kind,
+        materialSchemaJson: projectSchema(method.material),
+        metadataJson: authMethodMetadataJson(method),
+        name: method.name,
+        providerId: plugin.identifier,
+        setupSchemaJson: method.setup === undefined ? null : projectSchema(method.setup),
+      })),
+      capabilityVersions: capabilityVersionsByProvider.get(plugin.identifier) ?? [],
+      categories: plugin.categories,
+      description: plugin.description,
+      docsUrl: plugin.docsUrl,
+      homepageUrl: plugin.homepageUrl,
+      iconUrl: plugin.iconUrl,
+      iconUrlDark: plugin.iconUrlDark,
+      id: plugin.identifier,
+      key: plugin.identifier,
+      kind: "tools" as const,
+      name: plugin.name,
+      sandboxAccess: plugin.sandboxAccess !== undefined,
+      sourcePluginKey: plugin.identifier,
+      sourcePluginVersion: version,
+    }),
+  );
+
+  const aiProviders: readonly MaterializedProvider[] = input.aiProviders.flatMap(provider => {
+    const id = AiProvider.registryId(provider.identifier);
+
+    return [
+      {
+        authMethods: provider.authMethods.map(method => ({
+          description: method.description,
+          id: authMethodId(id, method.identifier),
+          inputSchemaJson: method.input === undefined ? null : projectSchema(method.input),
+          key: method.identifier,
+          kind: method.kind,
+          materialSchemaJson: projectSchema(method.material),
+          metadataJson: authMethodMetadataJson(method),
+          name: method.name,
+          providerId: id,
+          setupSchemaJson: method.setup === undefined ? null : projectSchema(method.setup),
+        })),
+        capabilityVersions: [],
+        categories: provider.categories,
+        description: provider.description,
+        docsUrl: provider.docsUrl,
+        homepageUrl: provider.homepageUrl,
+        iconUrl: provider.iconUrl,
+        iconUrlDark: provider.iconUrlDark,
+        id,
+        key: provider.identifier,
+        kind: "ai" as const,
+        name: provider.name,
+        sandboxAccess: false,
+        sourcePluginKey: undefined,
+        sourcePluginVersion: undefined,
+      },
+    ];
+  });
+
+  return { dualIdentifier: input.dualIdentifier, providers: [...toolProviders, ...aiProviders] };
+};

package/src/internal/dual/triggers.ts

@@ -0,0 +1,128 @@
+import type * as AuthMethod from "../../AuthMethod.ts";
+import type { PluginInstallation } from "../../DualRuntime.ts";
+import type * as Group from "../../Group.ts";
+import type * as Plugin from "../../Plugin.ts";
+import type * as Trigger from "../../Trigger.ts";
+import { walkCapabilities } from "../capabilities.ts";
+import type { MachineIdSeparator } from "../identifier.ts";
+import type { IsAny, IsGenericArray } from "../types.ts";
+
+export interface TriggerEntry<
+  Id extends string = string,
+  ProviderId extends string = string,
+  TriggerDef extends Trigger.Any = Trigger.Any,
+  AllowedMethods extends readonly AuthMethod.Any[] = readonly AuthMethod.Any[],
+> {
+  readonly triggerId: Id;
+  readonly providerId: ProviderId;
+  readonly trigger: TriggerDef;
+  readonly authMethods: AllowedMethods;
+}
+
+type TriggerEntriesFromTriggers<
+  Triggers extends readonly Trigger.Any[],
+  ProviderId extends string,
+  Prefix extends string,
+  AllowedMethods extends readonly AuthMethod.Any[],
+> =
+  IsGenericArray<Triggers> extends true
+    ? TriggerEntry<string, ProviderId, Trigger.Any, AllowedMethods>
+    : Triggers[number] extends infer TriggerDef
+      ? TriggerDef extends Trigger.Any
+        ? TriggerEntry<
+            `${Prefix}${typeof MachineIdSeparator}${TriggerDef["identifier"]}`,
+            ProviderId,
+            TriggerDef,
+            AllowedMethods
+          >
+        : never
+      : never;
+
+type TriggerEntriesFromGroups<
+  Groups extends readonly Group.Any[],
+  ProviderId extends string,
+  Prefix extends string,
+  AllowedMethods extends readonly AuthMethod.Any[],
+> =
+  IsGenericArray<Groups> extends true
+    ? TriggerEntry<string, ProviderId, Trigger.Any, AllowedMethods>
+    : Groups[number] extends infer GroupDef
+      ? GroupDef extends Group.Any
+        ? GroupTriggerEntries<
+            GroupDef,
+            ProviderId,
+            `${Prefix}${typeof MachineIdSeparator}${GroupDef["identifier"]}`,
+            AllowedMethods
+          >
+        : never
+      : never;
+
+type GroupTriggerEntries<
+  GroupDef extends Group.Any,
+  ProviderId extends string,
+  Prefix extends string,
+  AllowedMethods extends readonly AuthMethod.Any[],
+> =
+  | TriggerEntriesFromTriggers<GroupDef["triggers"], ProviderId, Prefix, AllowedMethods>
+  | TriggerEntriesFromGroups<GroupDef["groups"], ProviderId, Prefix, AllowedMethods>;
+
+type PluginTriggerEntries<P extends Plugin.Any> =
+  | TriggerEntriesFromTriggers<P["triggers"], P["identifier"], P["identifier"], P["authMethods"]>
+  | TriggerEntriesFromGroups<P["groups"], P["identifier"], P["identifier"], P["authMethods"]>;
+
+export type AllTriggerEntries<Plugins extends readonly Plugin.Any[]> =
+  IsAny<Plugins> extends true
+    ? TriggerEntry
+    : IsGenericArray<Plugins> extends true
+      ? TriggerEntry
+      : Plugins[number] extends infer P
+        ? P extends Plugin.Any
+          ? PluginTriggerEntries<P>
+          : never
+        : never;
+
+export interface RuntimeTriggerEntry<
+  out TriggerDef extends Trigger.Any = Trigger.Any,
+  out AllowedMethods extends readonly AuthMethod.Any[] = readonly AuthMethod.Any[],
+  out TriggerId extends string = string,
+  out ProviderId extends string = string,
+> extends Trigger.RuntimeTriggerEntry<TriggerDef, AllowedMethods, TriggerId, ProviderId> {
+  readonly localId: string;
+  readonly pluginVersion: string;
+}
+
+const entriesOf = (installation: PluginInstallation): readonly RuntimeTriggerEntry[] =>
+  walkCapabilities(installation.plugin, owner => owner.triggers).map(walked => ({
+    authMethods: installation.plugin.authMethods,
+    localId: walked.localId,
+    pluginVersion: installation.version,
+    providerId: installation.plugin.identifier,
+    trigger: walked.node,
+    triggerId: walked.canonicalId,
+  }));
+
+export const collectTriggerEntries = (
+  installations: readonly PluginInstallation[],
+): readonly RuntimeTriggerEntry[] => installations.flatMap(entriesOf);
+
+const triggerIndex = new WeakMap<
+  readonly PluginInstallation[],
+  ReadonlyMap<string, RuntimeTriggerEntry>
+>();
+
+/** A trigger of the installed releases, or of the exact `version` when the caller pins one. */
+export const resolveRuntimeTrigger = (
+  installations: readonly PluginInstallation[],
+  triggerId: string,
+  version?: string,
+): RuntimeTriggerEntry | undefined => {
+  let index = triggerIndex.get(installations);
+  if (index === undefined) {
+    index = new Map(collectTriggerEntries(installations).map(entry => [entry.triggerId, entry]));
+    triggerIndex.set(installations, index);
+  }
+  const entry = index.get(triggerId);
+  return entry === undefined || (version !== undefined && entry.pluginVersion !== version)
+    ? undefined
+    : entry;
+};

package/src/internal/handler-context.ts

@@ -0,0 +1,57 @@
+/**
+ * A plugin's handlers live in the layer context as one group entry, keyed by
+ * plugin id, so merging layer outputs grows with the number of plugins and
+ * not with their actions. A handler keeps the services of its own build, never
+ * the groups of other plugins, and a runtime resolves groups through one
+ * index entry, so per-call context copies grow with the services in the app.
+ */
+import { Array, Context, Predicate, String } from "effect";
+
+const groupKeyPrefix = "@dual-os/sdk/Plugin/Handlers/";
+
+export const handlerGroupKey = (pluginId: string): string => `${groupKeyPrefix}${pluginId}`;
+
+const isGroupKey = String.startsWith(groupKeyPrefix);
+
+class HandlerIndex extends Context.Service<HandlerIndex, ReadonlyMap<string, unknown>>()(
+  "@dual-os/sdk/internal/handler-context/HandlerIndex",
+) {}
+
+export const withoutGroups = (context: Context.Context<never>): Context.Context<never> => {
+  const services = Array.filter(
+    Array.fromIterable(context.mapUnsafe),
+    entry => !isGroupKey(entry[0]),
+  );
+  return services.length === context.mapUnsafe.size
+    ? context
+    : Context.makeUnsafe(new Map(services));
+};
+
+export const indexGroups = (context: Context.Context<never>): Context.Context<never> => {
+  const entries = Array.fromIterable(context.mapUnsafe);
+  return Context.add(
+    Context.makeUnsafe(new Map(Array.filter(entries, entry => !isGroupKey(entry[0])))),
+    HandlerIndex,
+    new Map(Array.filter(entries, entry => isGroupKey(entry[0]))),
+  );
+};
+
+export const mergeUnder = <Input>(
+  lower: Context.Context<never>,
+  input: Context.Context<Input>,
+): Context.Context<Input> =>
+  Array.reduce(Array.fromIterable(lower.mapUnsafe), input, (merged, entry) =>
+    input.mapUnsafe.has(entry[0]) ? merged : Context.addUnsafe(merged, entry[0], entry[1]),
+  );
+
+export const findHandler = (
+  context: Context.Context<never>,
+  providerId: string,
+  handlerKey: string,
+): unknown => {
+  const groupKey = handlerGroupKey(providerId);
+  const group =
+    context.mapUnsafe.get(groupKey) ?? Context.getOrUndefined(context, HandlerIndex)?.get(groupKey);
+
+  return Predicate.isMap(group) ? group.get(handlerKey) : undefined;
+};

package/src/internal/identifier.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+
+import { InvalidIdentifierError, type DefinitionIdentifierKind } from "../DefinitionError.ts";
+
+export const MachineIdSeparator = "/" as const;
+
+const identifierSchema = Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/));
+const isIdentifier = Schema.is(identifierSchema);
+
+export const validateIdentifier = (kind: DefinitionIdentifierKind, identifier: string): void => {
+  if (identifier.length === 0) {
+    throw new InvalidIdentifierError({ identifier, kind, reason: "empty" });
+  }
+
+  if (identifier.includes(MachineIdSeparator)) {
+    throw new InvalidIdentifierError({
+      identifier,
+      kind,
+      reason: "contains-reserved-separator",
+      reservedCharacter: MachineIdSeparator,
+    });
+  }
+
+  if (!isIdentifier(identifier)) {
+    throw new InvalidIdentifierError({ identifier, kind, reason: "invalid-format" });
+  }
+};