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

package/src/internal/trigger-runtime.ts

@@ -0,0 +1,223 @@
+import type { Context } from "effect";
+import { Effect, Record, String } from "effect";
+
+import type * as Trigger from "../Trigger.ts";
+
+import type { RuntimeConnectionErrorsFor } from "./auth-execution.ts";
+import { mergeUnder } from "./handler-context.ts";
+import {
+  decodeConfig,
+  decodeState,
+  type EntryAuthMethods,
+  type EntryTrigger,
+  type TriggerAppError,
+  type TriggerEncodedState,
+  type TriggerEncodedOutput,
+  type TriggerIdOf,
+  type TriggerRuntimeRequirements,
+  requirePollingHook,
+  requireWebhookHook,
+  validateOutputs,
+  validateStateResult,
+  withRuntimeContext,
+} from "./trigger-runtime-shared.ts";
+
+/** Erased runtime entry: every phase implementation works on this view while
+ * the public signatures re-expose precise per-entry types. */
+type AnyEntry = Trigger.RuntimeTriggerEntry<
+  Trigger.Trigger<string, Trigger.TriggerKind, any, any, any, any>
+>;
+
+type PhaseHook<HookResult> = {
+  readonly hook: (input: any, context: any) => Effect.Effect<HookResult, any, any>;
+  readonly context: Context.Context<never>;
+};
+
+type PhaseError =
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.UnsupportedTriggerRuntimeError;
+
+/**
+ * Shared execution skeleton for all trigger runtime phases: decode config and
+ * state, resolve the runtime connection, run the hook inside the registered
+ * handler context, then hand the raw hook result to the phase finisher.
+ */
+const runPhase = <HookResult, Result>(options: {
+  readonly entry: AnyEntry;
+  readonly phase: Trigger.RuntimePhase;
+  readonly request: Trigger.LifecycleRequest;
+  readonly input?: object;
+  readonly hook: Effect.Effect<PhaseHook<HookResult>, Trigger.UnsupportedTriggerRuntimeError, any>;
+  readonly finish: (result: HookResult) => Effect.Effect<Result, unknown, unknown>;
+}): Effect.Effect<Result, PhaseError | unknown, unknown> =>
+  Effect.gen(function* () {
+    const { entry, phase, request } = options;
+    const runtime = yield* options.hook;
+    const config = yield* decodeConfig(entry.triggerId, entry.trigger.config, request.config);
+    const state = yield* decodeState(entry.triggerId, phase, entry.trigger.state, request.state);
+
+    const input = { ...options.input, config, state };
+
+    const result = yield* withRuntimeContext(
+      entry,
+      phase,
+      request.connectionId,
+      request.context,
+      context => Effect.suspend(() => runtime.hook(input, context)),
+    ).pipe(Effect.updateContext(current => mergeUnder(runtime.context, current)));
+
+    return yield* options.finish(result);
+  });
+
+const meta = <Phase extends Trigger.RuntimePhase>(entry: AnyEntry, phase: Phase) => ({
+  phase,
+  triggerId: entry.triggerId,
+});
+
+const finishEmit =
+  (entry: AnyEntry, phase: "parse" | "poll") => (emitted: Trigger.EmitResult<unknown, unknown>) =>
+    validateOutputs(entry.triggerId, phase, entry.trigger.output, emitted.events).pipe(
+      Effect.zip(validateStateResult(entry.triggerId, phase, entry.trigger.state, emitted.state)),
+      Effect.map(([events, state]) => ({ events, meta: meta(entry, phase), state })),
+    );
+
+export const activate: <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+  request: Trigger.WebhookActivationRequest,
+) => Effect.Effect<
+  Trigger.ActivateSuccess<TriggerIdOf<Entry>, TriggerEncodedState<EntryTrigger<Entry>>>,
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.UnsupportedTriggerRuntimeError
+  | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>
+  | TriggerAppError<EntryTrigger<Entry>>,
+  TriggerRuntimeRequirements<Entry, "activate">
+> = (entry, request) =>
+  runPhase({
+    entry,
+    finish: result =>
+      validateStateResult(entry.triggerId, "activate", entry.trigger.state, result.state).pipe(
+        Effect.map(state => ({ meta: meta(entry, "activate"), state })),
+      ),
+    hook: requireWebhookHook(entry, "activate"),
+    input: { webhookUrl: request.webhookUrl },
+    phase: "activate",
+    request,
+  });
+
+export const deactivate: <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+  request: Trigger.WebhookActivationRequest,
+) => Effect.Effect<
+  Trigger.DeactivateSuccess<TriggerIdOf<Entry>>,
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.UnsupportedTriggerRuntimeError
+  | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>
+  | TriggerAppError<EntryTrigger<Entry>>,
+  TriggerRuntimeRequirements<Entry, "deactivate">
+> = (entry, request) =>
+  runPhase({
+    entry,
+    finish: () => Effect.succeed({ meta: meta(entry, "deactivate") }),
+    hook: requireWebhookHook(entry, "deactivate"),
+    input: { webhookUrl: request.webhookUrl },
+    phase: "deactivate",
+    request,
+  });
+
+const lowercaseHeaders = (request: Trigger.WebhookRequest): Trigger.WebhookRequest =>
+  request.headers === undefined
+    ? request
+    : { ...request, headers: Record.mapKeys(request.headers, String.toLowerCase) };
+
+export const verify: <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+  request: Trigger.WebhookExecutionRequest,
+) => Effect.Effect<
+  Trigger.VerifySuccess<TriggerIdOf<Entry>, TriggerEncodedState<EntryTrigger<Entry>>>,
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.UnsupportedTriggerRuntimeError
+  | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>
+  | TriggerAppError<EntryTrigger<Entry>>,
+  TriggerRuntimeRequirements<Entry, "verify">
+> = (entry, request) =>
+  runPhase({
+    entry,
+    finish: Effect.fnUntraced(function* (result) {
+      const state = yield* validateStateResult(
+        entry.triggerId,
+        "verify",
+        entry.trigger.state,
+        result?.state,
+      );
+      return {
+        verified: true as const,
+        ...(result?.response === undefined ? {} : { response: result.response }),
+        ...(state === undefined ? {} : { state }),
+        meta: meta(entry, "verify"),
+      };
+    }),
+    hook: requireWebhookHook(entry, "verify"),
+    input: { request: lowercaseHeaders(request.request), webhookUrl: request.webhookUrl },
+    phase: "verify",
+    request,
+  });
+
+export const parse: <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+  request: Trigger.WebhookExecutionRequest,
+) => Effect.Effect<
+  Trigger.EmittedEventsSuccess<
+    TriggerIdOf<Entry>,
+    "parse",
+    TriggerEncodedOutput<EntryTrigger<Entry>>,
+    TriggerEncodedState<EntryTrigger<Entry>>
+  >,
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.InvalidTriggerOutputError
+  | Trigger.UnsupportedTriggerRuntimeError
+  | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>
+  | TriggerAppError<EntryTrigger<Entry>>,
+  TriggerRuntimeRequirements<Entry, "parse">
+> = (entry, request) =>
+  runPhase({
+    entry,
+    finish: finishEmit(entry, "parse"),
+    hook: requireWebhookHook(entry, "parse"),
+    input: { request: lowercaseHeaders(request.request), webhookUrl: request.webhookUrl },
+    phase: "parse",
+    request,
+  }) as never;
+
+export const poll: <Entry extends Trigger.RuntimeTriggerEntry<any, any, any, any>>(
+  entry: Entry,
+  request: Trigger.PollExecutionRequest,
+) => Effect.Effect<
+  Trigger.EmittedEventsSuccess<
+    TriggerIdOf<Entry>,
+    "poll",
+    TriggerEncodedOutput<EntryTrigger<Entry>>,
+    TriggerEncodedState<EntryTrigger<Entry>>
+  >,
+  | Trigger.InvalidTriggerConfigError
+  | Trigger.InvalidTriggerStateError
+  | Trigger.InvalidTriggerOutputError
+  | Trigger.UnsupportedTriggerRuntimeError
+  | RuntimeConnectionErrorsFor<EntryAuthMethods<Entry>>
+  | TriggerAppError<EntryTrigger<Entry>>,
+  TriggerRuntimeRequirements<Entry, "poll">
+> = (entry, request) =>
+  // Polling handlers are executed at least once per platform occurrence. Hosts
+  // pass stable occurrence metadata in request.context.source.metadata, so
+  // handlers should be GET-like/idempotent for repeated scheduledAt values.
+  runPhase({
+    entry,
+    finish: finishEmit(entry, "poll"),
+    hook: requirePollingHook(entry),
+    phase: "poll",
+    request,
+  }) as never;

package/src/internal/types.ts

@@ -0,0 +1,12 @@
+/** Small type-level utilities shared across the SDK internals. */
+import type { MachineIdSeparator } from "./identifier.ts";
+
+export type IsAny<Value> = 0 extends 1 & Value ? true : false;
+
+export type IsGenericArray<Values extends readonly unknown[]> = number extends Values["length"]
+  ? true
+  : false;
+
+export type JoinPrefix<Prefix extends string, Identifier extends string> = Prefix extends ""
+  ? Identifier
+  : `${Prefix}${typeof MachineIdSeparator}${Identifier}`;

package/src/remote-runtime.ts

@@ -0,0 +1,469 @@
+/**
+ * Data-only SDK lifecycle requests for an installed, isolated integration plugin.
+ *
+ * @since 0.3.0
+ */
+import {
+  Array,
+  Cause,
+  Effect,
+  Layer,
+  Match,
+  Option,
+  Predicate,
+  Redacted,
+  Schema,
+  flow,
+  pipe,
+} from "effect";
+
+import { HttpClient, HttpClientRequest } from "effect/http";
+import type { HttpClientResponse } from "effect/http";
+
+import { ActionHandlerError, RetryableActionHandlerError } from "./Action.ts";
+import * as AgentChannel from "./AgentChannel.ts";
+import { AuthMethodExecution } from "./AuthMethodExecution.ts";
+import { ConnectionResolver } from "./ConnectionResolver.ts";
+import { DualRuntime } from "./DualRuntime.ts";
+import { Files } from "./Files.ts";
+
+export type Identity = typeof Identity.Type;
+export const Identity = Schema.Struct({
+  artifactDigest: Schema.String.check(Schema.isPattern(/^[a-f0-9]{128}$/u)),
+  invocationId: Schema.NonEmptyString,
+  organizationId: Schema.NonEmptyString,
+  pluginKey: Schema.NonEmptyString,
+  pluginVersion: Schema.NonEmptyString,
+});
+
+const connection = Schema.Struct({
+  connectionId: Schema.NonEmptyString,
+  material: Schema.Json,
+  methodId: Schema.NonEmptyString,
+  providerId: Schema.NonEmptyString,
+  setup: Schema.optionalKey(Schema.Json),
+});
+const context = Schema.Struct({
+  actor: Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("user"), userId: Schema.NonEmptyString }),
+    Schema.Struct({ kind: Schema.Literal("system"), reason: Schema.optionalKey(Schema.String) }),
+  ]),
+  metadata: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+  source: Schema.Struct({
+    kind: Schema.NonEmptyString,
+    metadata: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+    subjectId: Schema.optionalKey(Schema.String),
+  }),
+  tenant: Schema.Struct({ organizationId: Schema.NonEmptyString, teamId: Schema.NonEmptyString }),
+});
+const trigger = {
+  config: Schema.Json,
+  state: Schema.optionalKey(Schema.Json),
+  triggerId: Schema.NonEmptyString,
+};
+const webhook = { ...trigger, webhookUrl: Schema.String };
+const channel = {
+  channelId: Schema.NonEmptyString,
+  definitionSettings: Schema.Json,
+  deploymentSettings: Schema.Json,
+};
+const delivery = {
+  ...webhook,
+  request: Schema.Struct({
+    body: Schema.Json,
+    headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    method: Schema.optionalKey(Schema.String),
+    query: Schema.optionalKey(
+      Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Array(Schema.String)])),
+    ),
+    rawBody: Schema.Uint8ArrayFromBase64,
+    url: Schema.optionalKey(Schema.String),
+  }),
+};
+export type Operation = typeof Operation.Type;
+export const Operation = Schema.Union([
+  Schema.TaggedStruct("invoke", { actionId: Schema.NonEmptyString, input: Schema.Json }),
+  Schema.TaggedStruct("activate", webhook),
+  Schema.TaggedStruct("deactivate", webhook),
+  Schema.TaggedStruct("verify", delivery),
+  Schema.TaggedStruct("parse", delivery),
+  Schema.TaggedStruct("poll", trigger),
+  Schema.TaggedStruct("channelCheckAccess", {
+    ...channel,
+    identity: AgentChannel.VerifiedIdentity,
+  }),
+  Schema.TaggedStruct("channelExecute", { ...channel, command: Schema.Json }),
+  AuthMethodExecution.JsonRequest,
+]);
+/** Where this call reads and stores the caller's files, and the token that lets it. */
+export type FileAccess = typeof FileAccess.Type;
+export const FileAccess = Schema.Struct({ token: Schema.NonEmptyString, url: Schema.String });
+export type Request = typeof Request.Type;
+export const Request = Schema.Struct({
+  connection: Schema.optionalKey(connection),
+  context,
+  files: Schema.optionalKey(FileAccess),
+  identity: Identity,
+  operation: Operation,
+});
+
+export type Failure = typeof Failure.Type;
+export const Failure = Schema.Struct({
+  category: Schema.Literals(["validation", "connection", "handler", "initialization", "protocol"]),
+  /** The Agent Channel failure the host rebuilds as its `ChannelError`. */
+  channel: Schema.optionalKey(
+    Schema.Struct({
+      code: AgentChannel.ErrorCode,
+      providerCode: Schema.optionalKey(AgentChannel.FailureCode),
+    }),
+  ),
+  code: Schema.String,
+  fields: Schema.optionalKey(Schema.Array(Schema.Struct({ path: Schema.String }))),
+  message: Schema.String,
+  retryAfterSeconds: Schema.optionalKey(Schema.Finite),
+  retryable: Schema.Boolean,
+  /** The provider's HTTP status, kept so the host can report why a provider rejected the call. */
+  status: Schema.optionalKey(Schema.Int),
+});
+export type Response = typeof Response.Type;
+export const Response = Schema.Union([
+  Schema.TaggedStruct("success", { identity: Identity, value: Schema.optionalKey(Schema.Json) }),
+  Schema.TaggedStruct("failure", { error: Failure, identity: Identity }),
+]);
+
+// Plugin causes and schema descriptions can contain credentials or submitted input.
+export function failure(error: unknown): Failure {
+  if (Schema.is(AgentChannel.ChannelError)(error)) {
+    return {
+      category: "handler",
+      channel: Option.match(Option.fromUndefinedOr(error.providerCode), {
+        onNone: () => ({ code: error.code }),
+        onSome: providerCode => ({ code: error.code, providerCode }),
+      }),
+      code: error._tag,
+      message: "Agent Channel operation failed",
+      retryable: false,
+    };
+  }
+  if (
+    Schema.is(Files.FileError)(error) ||
+    (Schema.is(ActionHandlerError)(error) && Schema.is(Files.FileError)(error.cause))
+  ) {
+    return {
+      category: "handler",
+      code: "FileError",
+      message: "A Dual Files operation failed",
+      retryable: false,
+    };
+  }
+  if (
+    Schema.is(DualRuntime.InvalidActionInputError)(error) ||
+    Schema.is(DualRuntime.InvalidActionOutputError)(error)
+  ) {
+    return {
+      category: "validation",
+      code: error._tag,
+      fields: Array.map(error.fields, field => ({ path: field.path })),
+      message: "Plugin action validation failed",
+      retryable: false,
+    };
+  }
+  if (Schema.is(RetryableActionHandlerError)(error)) {
+    return {
+      category: "handler",
+      code: error._tag,
+      message: "Plugin handler failed",
+      retryable: true,
+      ...Option.match(Option.fromUndefinedOr(error.retryAfterSeconds), {
+        onNone: () => ({}),
+        onSome: seconds => ({ retryAfterSeconds: seconds }),
+      }),
+    };
+  }
+  const tag =
+    Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag)
+      ? error._tag
+      : "PluginHandlerError";
+  const category = pipe(
+    Match.value(tag),
+    Match.when("SchemaError", () => "validation" as const),
+    Match.whenOr(
+      "InvalidTriggerConfigError",
+      "InvalidTriggerStateError",
+      "InvalidTriggerOutputError",
+      () => "validation" as const,
+    ),
+    Match.whenOr(
+      "ConnectionRequiredError",
+      "InvalidConnectionIdError",
+      "InvalidResolvedConnectionError",
+      "ConnectionIdNotAllowedError",
+      "AuthMethodNotFoundError",
+      "AuthMethodHookError",
+      "ExpectedOAuth2MethodError",
+      "OAuth2RefreshTokenUnavailableError",
+      () => "connection" as const,
+    ),
+    Match.orElse(() => "handler" as const),
+  );
+  return {
+    category,
+    code: Array.contains(
+      [
+        "SchemaError",
+        "InvalidTriggerConfigError",
+        "InvalidTriggerStateError",
+        "InvalidTriggerOutputError",
+        "ConnectionRequiredError",
+        "InvalidConnectionIdError",
+        "InvalidResolvedConnectionError",
+        "ConnectionIdNotAllowedError",
+        "AuthMethodNotFoundError",
+        "AuthMethodHookError",
+        "ExpectedOAuth2MethodError",
+        "OAuth2RefreshTokenUnavailableError",
+        "ActionNotFoundError",
+        "ActionHandlerNotFoundError",
+        "ActionHandlerError",
+        "TriggerNotFoundError",
+        "UnsupportedTriggerRuntimeError",
+        "FileError",
+        "SandboxAccessNotDeclaredError",
+        "SandboxRequestNotAllowedError",
+      ],
+      tag,
+    )
+      ? tag
+      : "PluginHandlerError",
+    message: "Plugin operation failed",
+    retryable: false,
+    ...(Schema.is(ActionHandlerError)(error) && Schema.is(Schema.Int)(error.status)
+      ? { status: error.status }
+      : {}),
+  };
+}
+
+const unavailableFiles = Files.Service.of({
+  read: () =>
+    Effect.fail(Files.FileError.make({ message: "Dual Files is not available to this operation" })),
+  write: () =>
+    Effect.fail(Files.FileError.make({ message: "Dual Files is not available to this operation" })),
+});
+export const filesUnavailable = Layer.succeed(Files.Service, unavailableFiles);
+
+const FileFailure = Schema.Struct({ message: Schema.String });
+
+// The host's file routes do the reading and storing, as the caller the token names.
+function filesService(access: FileAccess, http: HttpClient.HttpClient) {
+  const client = HttpClient.mapRequest(
+    http,
+    flow(
+      HttpClientRequest.prependUrl(`${access.url}/api/plugin-files`),
+      HttpClientRequest.bearerToken(access.token),
+    ),
+  );
+  function call<A>(
+    request: HttpClientRequest.HttpClientRequest,
+    read: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<A, unknown>,
+  ) {
+    return pipe(
+      Effect.gen(function* () {
+        const response = yield* client.execute(request);
+        if (response.status < 200 || response.status >= 300) {
+          return yield* Files.FileError.make(
+            yield* Schema.decodeUnknownEffect(FileFailure)(yield* response.json),
+          );
+        }
+        return yield* read(response);
+      }),
+      Effect.mapError(cause =>
+        Schema.is(Files.FileError)(cause)
+          ? cause
+          : Files.FileError.make({
+              cause: Redacted.make(cause),
+              message: "Cannot reach Dual Files",
+            }),
+      ),
+    );
+  }
+  return Files.Service.of({
+    read: file =>
+      call(HttpClientRequest.get(`/${encodeURIComponent(file.id)}`), response =>
+        Effect.map(response.arrayBuffer, buffer => new Uint8Array(buffer)),
+      ),
+    write: file =>
+      call(
+        pipe(
+          HttpClientRequest.post("", { urlParams: { name: file.name } }),
+          HttpClientRequest.bodyUint8Array(file.bytes, file.contentType ?? undefined),
+        ),
+        response => Effect.flatMap(response.json, Schema.decodeUnknownEffect(Files.File)),
+      ),
+  });
+}
+
+function connectionService(request: Request) {
+  return ConnectionResolver.Service.of({
+    resolve: input => {
+      const selected = request.connection;
+      if (selected === undefined) {
+        return Effect.fail(ConnectionResolver.ConnectionRequiredError.make(input.target));
+      }
+      if (
+        selected.providerId !== input.target.providerId ||
+        (input.connectionId !== undefined && input.connectionId !== selected.connectionId)
+      ) {
+        return Effect.fail(
+          ConnectionResolver.InvalidConnectionIdError.make({
+            ...input.target,
+            connectionId: input.connectionId ?? selected.connectionId,
+          }),
+        );
+      }
+      return Effect.succeed({ ...selected, encoding: "json" as const, setup: selected.setup });
+    },
+  });
+}
+export function connectionLayer(request: Request) {
+  return Layer.succeed(ConnectionResolver.Service, connectionService(request));
+}
+
+const run = Effect.fnUntraced(
+  function* (request: Request) {
+    const runtime = yield* DualRuntime.Service;
+    const connectionId = Option.match(Option.fromUndefinedOr(request.connection), {
+      onNone: () => ({}),
+      onSome: selected => ({ connectionId: selected.connectionId }),
+    });
+    const target = {
+      ...connectionId,
+      context: request.context,
+      pluginKey: request.identity.pluginKey,
+    };
+    const operation = request.operation;
+    if (operation._tag === "invoke") {
+      return yield* runtime.invokeJson({ ...operation, ...target });
+    }
+    if (operation._tag === "poll") {
+      const result = yield* flow(
+        runtime.pollTrigger,
+        Effect.mapError(failure),
+      )({ ...operation, ...target });
+      if (result.state === undefined) return { events: result.events, meta: result.meta };
+      return result;
+    }
+    if (operation._tag === "activate") {
+      const result = yield* flow(
+        runtime.activateTrigger,
+        Effect.mapError(failure),
+      )({ ...operation, ...target });
+      if (result.state === undefined) return { meta: result.meta };
+      return result;
+    }
+    if (operation._tag === "deactivate") {
+      return yield* flow(
+        runtime.deactivateTrigger,
+        Effect.mapError(failure),
+      )({ ...operation, ...target });
+    }
+    if (operation._tag === "verify") {
+      return yield* flow(
+        runtime.verifyTrigger,
+        Effect.mapError(failure),
+      )({ ...operation, ...target });
+    }
+    if (operation._tag === "parse") {
+      const result = yield* flow(
+        runtime.parseTrigger,
+        Effect.mapError(failure),
+      )({ ...operation, ...target });
+      if (result.state === undefined) return { events: result.events, meta: result.meta };
+      return result;
+    }
+    if (operation._tag === "channelCheckAccess") {
+      return yield* runtime.checkAccessAgentChannel({
+        channelId: operation.channelId,
+        definitionSettings: operation.definitionSettings,
+        deploymentSettings: operation.deploymentSettings,
+        identity: operation.identity,
+        ...connectionId,
+      });
+    }
+    if (operation._tag === "channelExecute") {
+      return yield* runtime.executeAgentChannel({
+        channelId: operation.channelId,
+        command: operation.command,
+        definitionSettings: operation.definitionSettings,
+        deploymentSettings: operation.deploymentSettings,
+        ...connectionId,
+      });
+    }
+
+    return yield* runtime.executeAuthJson(operation);
+  },
+  Effect.mapError(error => (Schema.is(Failure)(error) ? error : failure(error))),
+);
+
+/** Execute only in the guest after importing and building its installed plugin. */
+export const execute = Effect.fn("RemoteRuntime.execute")(function* (request: Request) {
+  // The guest runner supplies its fetch client; a host calling in-process has no file routes to reach.
+  const http = yield* Effect.serviceOption(HttpClient.HttpClient);
+  if (request.identity.organizationId !== request.context.tenant.organizationId) {
+    return {
+      _tag: "failure",
+      error: {
+        category: "protocol",
+        code: "OrganizationMismatch",
+        message: "Invocation organization does not match its context",
+        retryable: false,
+      },
+      identity: request.identity,
+    } satisfies Response;
+  }
+  return yield* pipe(
+    run(request),
+    Effect.provideService(ConnectionResolver.Service, connectionService(request)),
+    Effect.provideService(
+      Files.Service,
+      pipe(
+        Option.fromUndefinedOr(request.files),
+        Option.flatMap(access => Option.map(http, client => filesService(access, client))),
+        Option.getOrElse(() => unavailableFiles),
+      ),
+    ),
+    Effect.flatMap(
+      Effect.fnUntraced(function* (value) {
+        if (value === undefined) {
+          return { _tag: "success", identity: request.identity } satisfies Response;
+        }
+        return {
+          _tag: "success",
+          identity: request.identity,
+          value: yield* pipe(
+            Schema.decodeUnknownEffect(Schema.Json)(value),
+            Effect.mapError(failure),
+          ),
+        } satisfies Response;
+      }),
+    ),
+    Effect.catch(error =>
+      Effect.succeed({ _tag: "failure", error, identity: request.identity } satisfies Response),
+    ),
+    Effect.catchCauseIf(
+      cause => !Cause.hasInterrupts(cause),
+      () =>
+        Effect.succeed({
+          _tag: "failure",
+          error: {
+            category: "handler",
+            code: "PluginDefect",
+            message: "Plugin operation failed",
+            retryable: false,
+          },
+          identity: request.identity,
+        } satisfies Response),
+    ),
+  );
+});
+
+export * as RemoteRuntime from "./remote-runtime.ts";