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

package/src/ConnectionResolver.ts

@@ -0,0 +1,265 @@
+/**
+ * Host-provided connection resolution contracts for SDK execution flows.
+ *
+ * @since 0.0.0
+ */
+import type { Effect } from "effect";
+import { Context, Schema } from "effect";
+
+/**
+ * Connection-aware runtime targets supported by the SDK.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type ConnectionTargetKind = "action" | "trigger" | "ai_model" | "agent-channel";
+
+/**
+ * Tenant boundary for connection resolution and audit.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ConnectionResolutionTenant {
+  readonly organizationId: string;
+  readonly teamId: string;
+}
+
+/**
+ * Product actor on whose behalf a connection is being selected.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type ConnectionResolutionActor =
+  | { readonly kind: "user"; readonly userId: string }
+  | { readonly kind: "system"; readonly reason?: string | undefined };
+
+/**
+ * Product source that caused the invocation.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ConnectionResolutionSource {
+  readonly kind: string;
+  readonly subjectId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Host-owned context used to select, authorize, and audit a connection.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ConnectionResolutionContext {
+  readonly tenant?: ConnectionResolutionTenant;
+  readonly actor?: ConnectionResolutionActor;
+  readonly source?: ConnectionResolutionSource;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Request sent to the host connection resolver during action or trigger execution.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface ConnectionResolutionTarget {
+  readonly providerId: string;
+  readonly targetKind: ConnectionTargetKind;
+  readonly targetId: string;
+  readonly phase?: string;
+}
+
+export interface ResolveConnectionRequest {
+  readonly target: ConnectionResolutionTarget;
+  readonly connectionId?: string;
+  readonly context?: ConnectionResolutionContext;
+}
+
+export interface ResolvedConnectionMaterial {
+  readonly encoding?: "json";
+  readonly providerId: string;
+  readonly connectionId: string;
+  readonly methodId: string;
+  readonly material: unknown;
+  readonly setup: unknown;
+}
+
+/**
+ * Raised when a runtime target does not accept a connection but a connectionId was still provided.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ConnectionIdNotAllowedError extends Schema.TaggedError<ConnectionIdNotAllowedError>()(
+  "ConnectionIdNotAllowedError",
+  {
+    connectionId: Schema.String,
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when execution requires a connection and no compatible binding is available.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ConnectionRequiredError extends Schema.TaggedError<ConnectionRequiredError>()(
+  "ConnectionRequiredError",
+  {
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when several compatible connection bindings exist and the caller must choose one.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ConnectionSelectionRequiredError extends Schema.TaggedError<ConnectionSelectionRequiredError>()(
+  "ConnectionSelectionRequiredError",
+  {
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when the requested connectionId does not resolve to a compatible binding.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class InvalidConnectionIdError extends Schema.TaggedError<InvalidConnectionIdError>()(
+  "InvalidConnectionIdError",
+  {
+    connectionId: Schema.String,
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when the resolved connection value does not satisfy the selected auth method schema.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class InvalidResolvedConnectionError extends Schema.TaggedError<InvalidResolvedConnectionError>()(
+  "InvalidResolvedConnectionError",
+  {
+    description: Schema.String,
+    methodId: Schema.String,
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when the provider refuses the connection's stored grant, so the user must sign in again.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ConnectionReauthorizationRequiredError extends Schema.TaggedError<ConnectionReauthorizationRequiredError>()(
+  "ConnectionReauthorizationRequiredError",
+  {
+    connectionId: Schema.String,
+    message: Schema.String,
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Raised when the host credential store cannot be read during connection resolution.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class ConnectionResolverStoreError extends Schema.TaggedError<ConnectionResolverStoreError>()(
+  "ConnectionResolverStoreError",
+  {
+    cause: Schema.Defect(),
+    operation: Schema.String,
+    phase: Schema.optional(Schema.String),
+    providerId: Schema.String,
+    targetId: Schema.String,
+    targetKind: Schema.Literals(["action", "trigger", "ai_model", "agent-channel"]),
+  },
+) {}
+
+/**
+ * Structured connection failures surfaced by SDK runtime boundaries.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export type ConnectionError =
+  | ConnectionIdNotAllowedError
+  | ConnectionRequiredError
+  | ConnectionSelectionRequiredError
+  | InvalidConnectionIdError
+  | InvalidResolvedConnectionError
+  | ConnectionReauthorizationRequiredError
+  | ConnectionResolverStoreError;
+
+/**
+ * Errors the host resolver itself is expected to surface.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export type ResolveConnectionError =
+  | ConnectionRequiredError
+  | ConnectionSelectionRequiredError
+  | InvalidConnectionIdError
+  | InvalidResolvedConnectionError
+  | ConnectionReauthorizationRequiredError
+  | ConnectionResolverStoreError;
+
+/**
+ * Host-provided service used by SDK runtimes to select one concrete connection binding.
+ *
+ * The SDK narrows and validates this untyped host binding against the target's allowed methods
+ * before exposing it to handlers.
+ *
+ * @since 0.0.0
+ * @category services
+ */
+export interface ConnectionResolverInstance {
+  readonly resolve: (
+    input: ResolveConnectionRequest,
+  ) => Effect.Effect<ResolvedConnectionMaterial, ResolveConnectionError>;
+}
+
+/**
+ * Host-provided connection resolver service.
+ *
+ * @since 0.0.0
+ * @category services
+ */
+export class Service extends Context.Service<Service, ConnectionResolverInstance>()(
+  "@dual-os/sdk/ConnectionResolver",
+) {}
+
+export * as ConnectionResolver from "./ConnectionResolver.ts";

package/src/DefinitionError.ts

@@ -0,0 +1,115 @@
+/**
+ * Public SDK definition errors.
+ *
+ * @since 0.0.0
+ */
+import { Schema } from "effect";
+
+/**
+ * @since 0.0.0
+ * @category models
+ */
+export type DefinitionIdentifierKind =
+  | "dual"
+  | "plugin"
+  | "provider"
+  | "group"
+  | "action"
+  | "trigger"
+  | "auth-method"
+  | "agent-channel";
+
+/**
+ * @since 0.0.0
+ * @category models
+ */
+export type DefinitionOwnerKind = "dual" | "plugin" | "group";
+
+/**
+ * @since 0.0.0
+ * @category models
+ */
+export type DefinitionChildKind =
+  | "plugin"
+  | "provider"
+  | "group"
+  | "action"
+  | "trigger"
+  | "agent-channel";
+
+/**
+ * @since 0.0.0
+ * @category models
+ */
+export type InvalidIdentifierReason = "empty" | "contains-reserved-separator" | "invalid-format";
+
+const DefinitionIdentifierKindSchema = Schema.Literals([
+  "dual",
+  "plugin",
+  "provider",
+  "group",
+  "action",
+  "trigger",
+  "auth-method",
+  "agent-channel",
+]);
+const DefinitionOwnerKindSchema = Schema.Literals(["dual", "plugin", "group"]);
+const DefinitionChildKindSchema = Schema.Literals([
+  "agent-channel",
+  "plugin",
+  "provider",
+  "group",
+  "action",
+  "trigger",
+]);
+const InvalidIdentifierReasonSchema = Schema.Literals([
+  "empty",
+  "contains-reserved-separator",
+  "invalid-format",
+]);
+
+/**
+ * Raised when a definition identifier does not satisfy SDK constraints.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class InvalidIdentifierError extends Schema.TaggedError<InvalidIdentifierError>()(
+  "InvalidIdentifierError",
+  {
+    identifier: Schema.String,
+    kind: DefinitionIdentifierKindSchema,
+    reason: InvalidIdentifierReasonSchema,
+    reservedCharacter: Schema.optional(Schema.Literals(["/"])),
+  },
+) {}
+
+/**
+ * Raised when two sibling definitions reuse the same identifier.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class BuilderCollisionError extends Schema.TaggedError<BuilderCollisionError>()(
+  "BuilderCollisionError",
+  {
+    childKind: DefinitionChildKindSchema,
+    childPluginIdentifier: Schema.optional(Schema.String),
+    existingChildKind: DefinitionChildKindSchema,
+    existingPluginIdentifier: Schema.optional(Schema.String),
+    identifier: Schema.String,
+    ownerIdentifier: Schema.String,
+    ownerKind: DefinitionOwnerKindSchema,
+  },
+) {}
+
+/**
+ * Raised when a provider reuses an auth method identifier.
+ *
+ * @since 0.0.0
+ * @category errors
+ */
+export class DuplicateAuthMethodIdentifierError extends Schema.TaggedError<DuplicateAuthMethodIdentifierError>()(
+  "DuplicateAuthMethodIdentifierError",
+  { identifier: Schema.String, providerIdentifier: Schema.String },
+) {}

package/src/DualRegistry.ts

@@ -0,0 +1,152 @@
+/**
+ * Dual registry resolution and materialization.
+ *
+ * @since 0.0.0
+ */
+import { Schema } from "effect";
+
+import type * as AiProvider from "./AiProvider.ts";
+import type { AnyApp, App } from "./DualRuntime.ts";
+import { collectActionEntries, type AllActionEntries } from "./internal/dual/actions.ts";
+import {
+  materializeResolvedRegistry,
+  type MaterializedRegistry,
+  type MaterializedRegistryOptions,
+} from "./internal/dual/registry.ts";
+import {
+  type AllTriggerEntries,
+  collectTriggerEntries,
+  type RuntimeTriggerEntry,
+  resolveRuntimeTrigger,
+} from "./internal/dual/triggers.ts";
+import type * as Plugin from "./Plugin.ts";
+
+/** Raised when a trigger lifecycle request references an unknown trigger id. */
+export class TriggerNotFoundError extends Schema.TaggedError<TriggerNotFoundError>()(
+  "TriggerNotFoundError",
+  { triggerId: Schema.String },
+) {}
+
+/**
+ * Enumerate the canonical machine ids for every action in the app.
+ *
+ * @since 0.0.0
+ * @category getters
+ */
+export const actionIds = <
+  const P extends Plugin.Any,
+  LayerOutput,
+  LayerError,
+  LayerRequirements,
+  const AiProviders extends readonly AiProvider.Any[],
+>(
+  app: App<P, LayerOutput, LayerError, LayerRequirements, AiProviders>,
+): readonly AllActionEntries<readonly [P]>["actionId"][] =>
+  // The ids are walked from the erased plugin trees; the signature carries their literal types.
+  collectActionEntries(app.plugins).map(entry => entry.actionId) as never;
+
+/**
+ * Enumerate the canonical machine ids for every trigger in the app.
+ *
+ * @since 0.0.0
+ * @category getters
+ */
+export const triggerIds = <
+  const P extends Plugin.Any,
+  LayerOutput,
+  LayerError,
+  LayerRequirements,
+  const AiProviders extends readonly AiProvider.Any[],
+>(
+  app: App<P, LayerOutput, LayerError, LayerRequirements, AiProviders>,
+): readonly AllTriggerEntries<readonly [P]>["triggerId"][] =>
+  // The ids are walked from the erased plugin trees; the signature carries their literal types.
+  collectTriggerEntries(app.plugins).map(entry => entry.triggerId) as never;
+
+/**
+ * Resolve one trigger entry from the app, including its auth methods.
+ *
+ * @since 0.0.0
+ * @category getters
+ */
+export const resolveTrigger = (
+  app: AnyApp,
+  triggerId: string,
+  options: { readonly triggerVersion?: string } = {},
+): RuntimeTriggerEntry | undefined =>
+  resolveRuntimeTrigger(app.plugins, triggerId, options.triggerVersion);
+
+/** @since 0.0.0 @category registry */
+export type {
+  MaterializedActionCapabilityVersion,
+  MaterializedChannelCapabilityVersion,
+  MaterializedAuthMethod,
+  MaterializedCapabilityVersion,
+  MaterializedProvider,
+  MaterializedRegistry,
+  MaterializedRegistryOptions,
+  MaterializedTriggerCapabilityVersion,
+} from "./internal/dual/registry.ts";
+
+/**
+ * Materialize the capability catalog of an app's installed releases.
+ *
+ * @since 0.0.0
+ * @category registry
+ */
+export const materializeRegistry = (
+  app: AnyApp,
+  options: MaterializedRegistryOptions = {},
+): MaterializedRegistry =>
+  materializeResolvedRegistry({
+    aiProviders: app.aiProviders,
+    dualIdentifier: app.identifier,
+    plugins: app.plugins,
+    projectSchemas: options.projectSchemas,
+    projections: options.projections,
+    schemaJson: options.schemaJson,
+  });
+
+/** The contracts of one plugin release. @since 0.0.0 @category registry */
+export interface MaterializedPlugin {
+  readonly pluginIdentifier: string;
+  readonly pluginVersion: string;
+  readonly providers: readonly MaterializedRegistry["providers"][number][];
+}
+
+/**
+ * Extract a release's contracts without building Layers or running handlers.
+ *
+ * @since 0.0.0
+ * @category registry
+ */
+export const materializePlugin = (
+  plugin: Plugin.Any,
+  options: MaterializedRegistryOptions & { readonly version: string },
+): MaterializedPlugin => ({
+  pluginIdentifier: plugin.identifier,
+  pluginVersion: options.version,
+  providers: materializeResolvedRegistry({
+    aiProviders: [],
+    dualIdentifier: plugin.identifier,
+    plugins: [{ plugin, version: options.version }],
+    projectSchemas: options.projectSchemas,
+    projections: options.projections,
+    schemaJson: options.schemaJson,
+  }).providers,
+});
+
+/** Every installed plugin release and its contracts. @since 0.0.0 @category registry */
+export const materializePlugins = (app: AnyApp, options: MaterializedRegistryOptions = {}) => {
+  const projections = options.projections ?? new Map<Schema.Top, unknown>();
+  return app.plugins.map(installation => ({
+    ...materializePlugin(installation.plugin, {
+      ...options,
+      projections,
+      version: installation.version,
+    }),
+    ordinal: 0,
+  }));
+};
+
+export * as DualRegistry from "./DualRegistry.ts";