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

package/src/index.ts

@@ -0,0 +1,158 @@
+/**
+ * @since 0.0.0
+ */
+
+/**
+ * Canonical action definition builders and types for the Dual SDK.
+ *
+ * @since 0.0.0
+ */
+export * as Action from "./Action.ts";
+
+export * as AgentChannel from "./AgentChannel.ts";
+
+/**
+ * Replays operations that providers declare safe to replay. At-most-once delivery executes once;
+ * the durable host owns its replay prohibition. Use an isolated provider test installation: this
+ * suite performs provider effects. The host supplies stable keys; the plugin must recover the same
+ * external subscription and emit the same provider event keys, even for a fresh receipt key.
+ * Boundary rejection and feature/auth matrices are covered by the SDK's public runtime tests.
+ */
+export * as AgentChannelConformance from "./AgentChannelConformance.ts";
+
+export * as AgentChannelRuntime from "./AgentChannelRuntime.ts";
+
+/**
+ * AI provider definitions for model authentication.
+ *
+ * AI providers share provider metadata and auth methods with Tools providers,
+ * but cannot contribute actions, triggers, or groups. Their identifier is a
+ * stable key matched exactly against Pi's `Model.provider` value.
+ *
+ * @since 0.0.0
+ */
+export * as AiProvider from "./AiProvider.ts";
+
+/**
+ * Canonical auth-method definition builders and types for the Dual SDK.
+ *
+ * A plugin's auth methods are shared by all its actions and triggers.
+ *
+ * @since 0.0.0
+ */
+export * as AuthMethod from "./AuthMethod.ts";
+
+/**
+ * Resolved auth method bindings exposed to action and trigger handlers.
+ *
+ * @since 0.0.0
+ */
+export * as AuthMethodBinding from "./AuthMethodBinding.ts";
+
+/**
+ * Credential decoding, hook execution, material refresh, and value resolution.
+ *
+ * @since 0.0.0
+ */
+export * as AuthMethodExecution from "./AuthMethodExecution.ts";
+
+/**
+ * Host-provided connection resolution contracts for SDK execution flows.
+ *
+ * @since 0.0.0
+ */
+export * as ConnectionResolver from "./ConnectionResolver.ts";
+
+/**
+ * Public SDK definition errors.
+ *
+ * @since 0.0.0
+ */
+export * as DefinitionError from "./DefinitionError.ts";
+
+/**
+ * Dual registry resolution and materialization.
+ *
+ * @since 0.0.0
+ */
+export * as DualRegistry from "./DualRegistry.ts";
+
+/**
+ * Dual action invocation, trigger lifecycle, and auth runtime.
+ *
+ * @since 0.0.0
+ */
+export * as DualRuntime from "./DualRuntime.ts";
+
+/**
+ * Files that actions take and return: a small reference in action data, with the bytes kept by the
+ * host and read or written through the host's file service.
+ *
+ * @since 0.1.0
+ */
+export * as Files from "./Files.ts";
+
+/**
+ * Canonical group definition builders and types for the Dual SDK.
+ *
+ * Groups are structural namespaces nested beneath providers or other groups.
+ *
+ * @since 0.0.0
+ */
+export * as Group from "./Group.ts";
+
+/**
+ * The HTTP runtime of generated API plugins: each operation's contract and call, request encoding,
+ * response decoding, continuation links, redirects and uploads.
+ *
+ * @since 0.0.0
+ */
+export * as Http from "./Http.ts";
+
+/**
+ * A Model Context Protocol client over Streamable HTTP: the session generated plugins call tools
+ * through and the CLI lists them with.
+ *
+ * @since 0.0.0
+ */
+export * as Mcp from "./Mcp.ts";
+
+/**
+ * Host service that refreshes OAuth2 tokens for SDK auth execution.
+ *
+ * @since 0.0.0
+ */
+export * as OAuth2TokenRefresher from "./OAuth2TokenRefresher.ts";
+
+/**
+ * Canonical plugin definition builders and types for the Dual SDK.
+ *
+ * A plugin is one integration: its auth methods, actions, triggers and Agent Channels.
+ *
+ * @since 0.0.0
+ */
+export * as Plugin from "./Plugin.ts";
+
+/**
+ * Data-only SDK lifecycle requests for an installed, isolated integration plugin.
+ *
+ * @since 0.3.0
+ */
+export * as RemoteRuntime from "./remote-runtime.ts";
+
+/**
+ * JSON-safe file results that hosts can persist without reconstructing displayed text.
+ *
+ * @since 0.0.0
+ */
+export * as ToolFile from "./ToolFile.ts";
+
+/**
+ * Canonical trigger definition builders, runtime contracts, and execution helpers for the Dual SDK.
+ *
+ * @since 0.0.0
+ */
+export * as Trigger from "./Trigger.ts";
+
+export * as PluginRuntime from "./PluginRuntime.ts";
+export * as OAuthFlow from "./OAuthFlow.ts";

package/src/internal/auth-context.ts

@@ -0,0 +1,27 @@
+import type * as AuthMethod from "../AuthMethod.ts";
+import type * as AuthMethodBinding from "../AuthMethodBinding.ts";
+
+/**
+ * Runtime handler context for a known effective provider auth-method set.
+ *
+ * Empty method sets erase auth. Concrete non-empty tuples require auth. Widened
+ * arrays remain optional because their emptiness is not statically known.
+ */
+export type ContextForMethods<Methods extends readonly AuthMethod.Any[]> =
+  Methods extends readonly []
+    ? {}
+    : number extends Methods["length"]
+      ? { readonly auth?: AuthMethodBinding.Context<Methods> }
+      : { readonly auth: AuthMethodBinding.Context<Methods> };
+
+/**
+ * Handler context for one contract. Auth is required only when the contract
+ * requires it for certain; `requireAuth: false` or an unknown flag keeps it optional.
+ */
+export type ContextForContract<Methods extends readonly AuthMethod.Any[], RequireAuth> = [
+  RequireAuth,
+] extends [true]
+  ? ContextForMethods<Methods>
+  : Methods extends readonly []
+    ? {}
+    : { readonly auth?: AuthMethodBinding.Context<Methods> };

package/src/internal/auth-execution.ts

@@ -0,0 +1,241 @@
+import type { Schema } from "effect";
+import { Effect } from "effect";
+
+import type * as AuthMethod from "../AuthMethod.ts";
+import * as AuthMethodBinding from "../AuthMethodBinding.ts";
+import * as AuthMethodExecution from "../AuthMethodExecution.ts";
+import {
+  type ConnectionReauthorizationRequiredError,
+  type ConnectionRequiredError,
+  type ConnectionSelectionRequiredError,
+  type ConnectionResolverStoreError,
+  type InvalidConnectionIdError,
+  ConnectionIdNotAllowedError,
+  ConnectionResolver,
+  type ConnectionResolutionContext,
+  type ConnectionTargetKind,
+  InvalidResolvedConnectionError,
+} from "../ConnectionResolver.ts";
+
+import { decodeJson } from "./schema-runtime.ts";
+
+export type NonEmptyReadonlyArray<A> = readonly [A, ...A[]];
+
+export type AuthSchemaRequirements<Methods extends readonly AuthMethod.Any[]> =
+  Methods[number] extends infer Method
+    ? Method extends AuthMethod.Any
+      ? Schema.Codec.DecodingServices<AuthMethod.ValueSchema<Method>>
+      : never
+    : never;
+
+/**
+ * Everything connection resolution may touch for one of the allowed methods:
+ * setup/material/value decoding plus the method's hook requirements.
+ *
+ * Hook dependencies are app-defined services a host cannot know about (a
+ * plugin's API client, a token issuer); surfacing them here keeps them in the
+ * requirement algebra so they are either discharged at the plugin/app
+ * definition via `provide` or demanded generically from whoever invokes.
+ */
+export type AuthResolutionRequirements<Methods extends readonly AuthMethod.Any[]> =
+  Methods[number] extends infer Method
+    ? Method extends AuthMethod.Any
+      ?
+          | (AuthMethod.SetupSchema<Method> extends Schema.Top
+              ? Schema.Codec.DecodingServices<AuthMethod.SetupSchema<Method>>
+              : never)
+          | Schema.Codec.DecodingServices<AuthMethod.MaterialSchema<Method>>
+          | Schema.Codec.DecodingServices<AuthMethod.ValueSchema<Method>>
+          | AuthMethod.Requirements<Method>
+      : never
+    : never;
+
+export type RuntimeConnectionErrorsFor<Methods extends readonly AuthMethod.Any[]> =
+  | ConnectionIdNotAllowedError
+  | ([Methods[number]] extends [never]
+      ? never
+      :
+          | ConnectionRequiredError
+          | ConnectionSelectionRequiredError
+          | InvalidConnectionIdError
+          | InvalidResolvedConnectionError
+          | ConnectionReauthorizationRequiredError
+          | ConnectionResolverStoreError);
+
+const knownAuthMethodIds = (methods: readonly AuthMethod.Any[]) =>
+  methods.map(method => method.identifier);
+
+const fullAuthMethodId = (providerId: string, method: AuthMethod.Any): string =>
+  `${providerId}/${method.identifier}`;
+
+const findMethod = (
+  providerId: string,
+  methods: readonly AuthMethod.Any[],
+  methodId: string,
+): AuthMethod.Any | undefined =>
+  methods.find(
+    method => method.identifier === methodId || fullAuthMethodId(providerId, method) === methodId,
+  );
+
+const invalidResolvedAuth = (
+  targetKind: ConnectionTargetKind,
+  targetId: string,
+  phase: string | undefined,
+  providerId: string,
+  methodId: string,
+  description: string,
+): InvalidResolvedConnectionError =>
+  new InvalidResolvedConnectionError({
+    description,
+    methodId,
+    phase,
+    providerId,
+    targetId,
+    targetKind,
+  });
+
+const makeAuthContext: <Methods extends readonly AuthMethod.Any[]>(
+  binding: AuthMethodBinding.BindingFor<Methods>,
+) => AuthMethodBinding.Context<Methods> = (binding: AuthMethodBinding.Binding) => {
+  const context = {
+    current: binding,
+    is(
+      methodOrBinding: AuthMethod.Any | AuthMethodBinding.Binding,
+      maybeMethod?: AuthMethod.Any,
+    ): boolean {
+      return maybeMethod === undefined
+        ? AuthMethodBinding.isBindingForMethod(context.current, methodOrBinding as AuthMethod.Any)
+        : AuthMethodBinding.isBindingForMethod(
+            methodOrBinding as AuthMethodBinding.Binding,
+            maybeMethod,
+          );
+    },
+    match(cases: Record<string, (binding: AuthMethodBinding.Binding) => unknown>) {
+      return cases[context.current.methodId]!(context.current);
+    },
+  };
+
+  return context as never;
+};
+
+export const noAuthRuntimeContext = (): Record<never, never> => ({});
+
+export const authRuntimeContext = <Methods extends readonly AuthMethod.Any[]>(
+  binding: AuthMethodBinding.BindingFor<Methods>,
+): { readonly auth: AuthMethodBinding.Context<Methods> } => ({ auth: makeAuthContext(binding) });
+
+export const toNonEmptyArray = <A>(values: readonly A[]): NonEmptyReadonlyArray<A> | undefined =>
+  values.length === 0 ? undefined : [values[0]!, ...values.slice(1)];
+
+export const failConnectionIdNotAllowed = (
+  targetKind: ConnectionTargetKind,
+  targetId: string,
+  phase: string | undefined,
+  providerId: string,
+  connectionId: string,
+): Effect.Effect<never, ConnectionIdNotAllowedError> =>
+  Effect.fail(
+    new ConnectionIdNotAllowedError({ connectionId, phase, providerId, targetId, targetKind }),
+  );
+
+export const resolveRuntimeConnection: <Methods extends NonEmptyReadonlyArray<AuthMethod.Any>>(
+  targetKind: ConnectionTargetKind,
+  targetId: string,
+  phase: string | undefined,
+  providerId: string,
+  methods: Methods,
+  connectionId: string | undefined,
+  context: ConnectionResolutionContext | undefined,
+) => Effect.Effect<
+  AuthMethodBinding.BindingFor<Methods>,
+  | ConnectionRequiredError
+  | ConnectionSelectionRequiredError
+  | InvalidConnectionIdError
+  | InvalidResolvedConnectionError
+  | ConnectionReauthorizationRequiredError
+  | ConnectionResolverStoreError,
+  ConnectionResolver.Service | AuthSchemaRequirements<Methods> | AuthResolutionRequirements<Methods>
+> = (
+  targetKind: ConnectionTargetKind,
+  targetId: string,
+  phase: string | undefined,
+  providerId: string,
+  methods: NonEmptyReadonlyArray<AuthMethod.Any>,
+  connectionId: string | undefined,
+  context: ConnectionResolutionContext | undefined,
+) =>
+  Effect.gen(function* () {
+    const resolver = yield* ConnectionResolver.Service;
+    const resolved = yield* resolver.resolve({
+      target: { providerId, targetId, targetKind, ...(phase === undefined ? {} : { phase }) },
+      ...(connectionId === undefined ? {} : { connectionId }),
+      ...(context === undefined ? {} : { context }),
+    });
+
+    if (resolved.providerId !== providerId) {
+      return yield* invalidResolvedAuth(
+        targetKind,
+        targetId,
+        phase,
+        providerId,
+        resolved.methodId,
+        `expected provider "${providerId}", got "${resolved.providerId}"`,
+      );
+    }
+
+    const method = findMethod(providerId, methods, resolved.methodId);
+    if (method === undefined) {
+      return yield* invalidResolvedAuth(
+        targetKind,
+        targetId,
+        phase,
+        providerId,
+        resolved.methodId,
+        `method "${resolved.methodId}" is not registered for provider "${providerId}"; known methods: ${knownAuthMethodIds(methods).join(", ")}`,
+      );
+    }
+
+    const setup = yield* (
+      resolved.encoding === "json" && method.setup !== undefined
+        ? decodeJson(method.setup, resolved.setup)
+        : AuthMethodExecution.decodeSetup(method, resolved.setup)
+    ).pipe(
+      Effect.mapError(error =>
+        invalidResolvedAuth(
+          targetKind,
+          targetId,
+          phase,
+          providerId,
+          method.identifier,
+          error.message,
+        ),
+      ),
+    );
+    const value = yield* (
+      resolved.encoding === "json"
+        ? decodeJson(method.material, resolved.material).pipe(
+            Effect.flatMap(material =>
+              AuthMethodExecution.resolveDecoded(method, material, { setup }),
+            ),
+          )
+        : AuthMethodExecution.resolveUnknown(method, resolved.material, { setup })
+    ).pipe(
+      Effect.mapError(error =>
+        invalidResolvedAuth(
+          targetKind,
+          targetId,
+          phase,
+          providerId,
+          method.identifier,
+          error instanceof Error ? error.message : String(error),
+        ),
+      ),
+    );
+
+    return AuthMethodBinding.makeBinding({
+      connectionId: resolved.connectionId,
+      method,
+      providerId,
+      value,
+    });
+  }) as never;

package/src/internal/auth-runtime.ts

@@ -0,0 +1,20 @@
+import type * as AuthMethod from "../AuthMethod.ts";
+import { DuplicateAuthMethodIdentifierError } from "../DefinitionError.ts";
+
+export const assertNoDuplicateAuthMethodIdentifiers = (
+  providerIdentifier: string,
+  methods: readonly AuthMethod.Any[],
+): void => {
+  const seen = new Set<string>();
+
+  for (const method of methods) {
+    if (seen.has(method.identifier)) {
+      throw new DuplicateAuthMethodIdentifierError({
+        identifier: method.identifier,
+        providerIdentifier,
+      });
+    }
+
+    seen.add(method.identifier);
+  }
+};

package/src/internal/capabilities.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared provider-tree traversal for capability nodes.
+ *
+ * Actions and triggers live in the same structural tree (provider -> nested
+ * groups) and need identical machine-id derivation, so the recursive walk
+ * lives here once and callers pick the node kind via `select`.
+ */
+import type * as Action from "../Action.ts";
+import type * as Group from "../Group.ts";
+import type * as Trigger from "../Trigger.ts";
+
+import { MachineIdSeparator } from "./identifier.ts";
+
+type StructuralOwner = {
+  readonly groups: readonly Group.Any[];
+  readonly actions: readonly Action.Any[];
+  readonly triggers: readonly Trigger.Any[];
+};
+
+export type WalkedCapability<Node> = {
+  /** Machine id relative to the provider (group path included). */
+  readonly localId: string;
+  /** Machine id including the provider prefix. */
+  readonly canonicalId: string;
+  readonly node: Node;
+};
+
+export const walkCapabilities = <Node extends { readonly identifier: string }>(
+  provider: StructuralOwner & { readonly identifier: string },
+  select: (owner: StructuralOwner) => readonly Node[],
+): readonly WalkedCapability<Node>[] => {
+  const entries: WalkedCapability<Node>[] = [];
+
+  const visit = (owner: StructuralOwner, prefix: string): void => {
+    for (const node of select(owner)) {
+      const localId =
+        prefix === "" ? node.identifier : `${prefix}${MachineIdSeparator}${node.identifier}`;
+      entries.push({
+        canonicalId: `${provider.identifier}${MachineIdSeparator}${localId}`,
+        localId,
+        node,
+      });
+    }
+
+    for (const group of owner.groups) {
+      visit(
+        group,
+        prefix === "" ? group.identifier : `${prefix}${MachineIdSeparator}${group.identifier}`,
+      );
+    }
+  };
+
+  visit(provider, "");
+  return entries;
+};

package/src/internal/children.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared structural-children machinery for Group and Plugin builders.
+ *
+ * Both owners accept the same mixed child set (groups, actions, triggers) and
+ * need identical type-level partitioning, runtime partitioning, and collision
+ * checks, so the logic lives here once.
+ */
+import * as Action from "../Action.ts";
+import { BuilderCollisionError } from "../DefinitionError.ts";
+import * as Group from "../Group.ts";
+import * as Trigger from "../Trigger.ts";
+
+export type StructuralChild = Group.Any | Action.Any | Trigger.Any;
+
+export type StructuralChildKind = "group" | "action" | "trigger" | "agent-channel";
+
+/**
+ * Keep the children assignable to `Target`, preserving tuple order.
+ */
+export type FilterChildren<
+  Children extends readonly StructuralChild[],
+  Target,
+> = Children extends readonly [infer Head, ...infer Tail extends readonly StructuralChild[]]
+  ? Head extends Target
+    ? readonly [Head, ...FilterChildren<Tail, Target>]
+    : FilterChildren<Tail, Target>
+  : readonly [];
+
+export type PartitionedChildren = {
+  readonly groups: readonly Group.Any[];
+  readonly actions: readonly Action.Any[];
+  readonly triggers: readonly Trigger.Any[];
+};
+
+export const partitionChildren = (children: readonly StructuralChild[]): PartitionedChildren => ({
+  actions: children.filter(Action.isAction),
+  groups: children.filter(Group.isGroup),
+  triggers: children.filter(Trigger.isTrigger),
+});
+
+const childKind = (child: StructuralChild): StructuralChildKind =>
+  Group.isGroup(child) ? "group" : Action.isAction(child) ? "action" : "trigger";
+
+type IdentifiedChild = { readonly identifier: string };
+
+type ExistingChildren = {
+  readonly groups: readonly IdentifiedChild[];
+  readonly actions: readonly IdentifiedChild[];
+  readonly triggers: readonly IdentifiedChild[];
+  readonly agentChannels?: readonly IdentifiedChild[];
+};
+
+const seenChildren = (existing: ExistingChildren): Map<string, StructuralChildKind> => {
+  const seen = new Map<string, StructuralChildKind>();
+
+  for (const group of existing.groups) {
+    seen.set(group.identifier, "group");
+  }
+
+  for (const action of existing.actions) {
+    seen.set(action.identifier, "action");
+  }
+
+  for (const trigger of existing.triggers) {
+    seen.set(trigger.identifier, "trigger");
+  }
+
+  for (const channel of existing.agentChannels ?? []) seen.set(channel.identifier, "agent-channel");
+  return seen;
+};
+
+const assertAdditions = (
+  ownerKind: "group" | "plugin",
+  ownerIdentifier: string,
+  seen: Map<string, StructuralChildKind>,
+  additions: readonly (readonly [IdentifiedChild, StructuralChildKind])[],
+): void => {
+  for (const [addition, kind] of additions) {
+    const existingChildKind = seen.get(addition.identifier);
+
+    if (existingChildKind !== undefined) {
+      throw new BuilderCollisionError({
+        childKind: kind,
+        existingChildKind,
+        identifier: addition.identifier,
+        ownerIdentifier,
+        ownerKind,
+      });
+    }
+
+    seen.set(addition.identifier, kind);
+  }
+};
+
+export const assertUniqueStructuralChildIdentifiers = (
+  ownerKind: "group" | "plugin",
+  ownerIdentifier: string,
+  existing: ExistingChildren,
+  additions: readonly IdentifiedChild[],
+  childKind: StructuralChildKind,
+): void => {
+  assertAdditions(
+    ownerKind,
+    ownerIdentifier,
+    seenChildren(existing),
+    additions.map(addition => [addition, childKind] as const),
+  );
+};
+
+/**
+ * Mixed-kind variant used by `add`: additions are checked in declaration order
+ * so a collision between two added children of different kinds is still caught.
+ */
+export const assertUniqueMixedChildIdentifiers = (
+  ownerKind: "group" | "plugin",
+  ownerIdentifier: string,
+  existing: ExistingChildren,
+  additions: readonly StructuralChild[],
+): void => {
+  assertAdditions(
+    ownerKind,
+    ownerIdentifier,
+    seenChildren(existing),
+    additions.map(addition => [addition, childKind(addition)] as const),
+  );
+};

package/src/internal/collection-utils.ts

@@ -0,0 +1,8 @@
+export const appendElements = <
+  Existing extends readonly unknown[],
+  Added extends readonly unknown[],
+>(
+  existing: Existing,
+  additions: Added,
+): readonly [...Existing, ...Added] =>
+  [...existing, ...additions] as readonly [...Existing, ...Added];