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

package/src/AgentChannelRuntime.ts

@@ -0,0 +1,616 @@
+/** Checked execution of pinned Agent Channel capabilities. No product lifecycle or persistence. */
+import { Cause, Context, Effect, Layer, Option, Predicate, Schema } from "effect";
+
+import * as AgentChannel from "./AgentChannel.ts";
+import { ConnectionResolver } from "./ConnectionResolver.ts";
+import type { AuthResolutionRequirements } from "./internal/auth-execution.ts";
+import { findHandler } from "./internal/handler-context.ts";
+import type * as Plugin from "./Plugin.ts";
+
+/** Host-only connection authority context. It is never included in handler inputs. */
+export const ConnectionContext = Schema.Struct({
+  actor: Schema.optionalKey(
+    Schema.Union([
+      Schema.Struct({ kind: Schema.Literal("user"), userId: AgentChannel.Key }),
+      Schema.Struct({
+        kind: Schema.Literal("system"),
+        reason: Schema.optionalKey(AgentChannel.Key),
+      }),
+    ]),
+  ),
+  source: Schema.optionalKey(
+    Schema.Struct({ kind: AgentChannel.Key, subjectId: Schema.optionalKey(AgentChannel.Key) }),
+  ),
+  tenant: Schema.optionalKey(
+    Schema.Struct({ organizationId: AgentChannel.Key, teamId: AgentChannel.Key }),
+  ),
+});
+const Pin = Schema.Struct({ channelId: AgentChannel.Key });
+const Input = Schema.Struct({
+  ...Pin.fields,
+  command: Schema.Unknown,
+  connectionId: Schema.optionalKey(AgentChannel.Key),
+  context: Schema.optionalKey(ConnectionContext),
+  definitionSettings: Schema.Unknown,
+  deploymentSettings: Schema.Unknown,
+});
+const AccessInput = Schema.Struct({
+  ...Pin.fields,
+  connectionId: Schema.optionalKey(AgentChannel.Key),
+  context: Schema.optionalKey(ConnectionContext),
+  definitionSettings: Schema.Unknown,
+  deploymentSettings: Schema.Unknown,
+  identity: AgentChannel.VerifiedIdentity,
+});
+export type Pin = typeof Pin.Type;
+export type Input = typeof Input.Type;
+export interface Interface {
+  /** Reauthorize an already verified identity; does not verify a transport or execute provider operations. */
+  readonly checkAccess: (
+    input: unknown,
+  ) => Effect.Effect<AgentChannel.AccessOutcome, AgentChannel.ChannelError>;
+  readonly get: (pin: unknown) => Effect.Effect<AgentChannel.Definition, AgentChannel.ChannelError>;
+  readonly decodeDefinitionSettings: (
+    input: unknown,
+  ) => Effect.Effect<Schema.Json, AgentChannel.ChannelError>;
+  readonly decodeDeploymentSettings: (
+    input: unknown,
+  ) => Effect.Effect<Schema.Json, AgentChannel.ChannelError>;
+  readonly execute: (
+    input: unknown,
+  ) => Effect.Effect<AgentChannel.CheckedResult, AgentChannel.ChannelError>;
+}
+export class Service extends Context.Service<Service, Interface>()(
+  "@dual-os/sdk/AgentChannelRuntime",
+) {}
+
+type Definitions<P extends Plugin.Any> = P["agentChannels"][number]["definition"];
+type ChannelHandlers<P extends Plugin.Any, C> = C extends AgentChannel.Any
+  ? AgentChannel.Handler<`${P["identifier"]}/${C["identifier"]}`>
+  : never;
+type PluginHandlers<P> = P extends Plugin.Any
+  ? ChannelHandlers<P, P["agentChannels"][number]>
+  : never;
+type ExtensionRequirements<D> = D extends {
+  readonly extensions: infer Extensions extends Readonly<Record<string, Schema.Top>>;
+}
+  ?
+      | Extensions[keyof Extensions]["DecodingServices"]
+      | Extensions[keyof Extensions]["EncodingServices"]
+  : never;
+export type Requirements<P extends Plugin.Any> =
+  | PluginHandlers<P>
+  | ExtensionRequirements<Definitions<P>>
+  | Definitions<P>["definitionSettings"]["DecodingServices"]
+  | Definitions<P>["deploymentSettings"]["DecodingServices"]
+  | Definitions<P>["state"]["DecodingServices"]
+  | Definitions<P>["state"]["EncodingServices"]
+  | AuthResolutionRequirements<Definitions<P>["authMethods"]>
+  | (Definitions<P>["authMethods"][number] extends never ? never : ConnectionResolver.Service);
+
+const fail = (code: typeof AgentChannel.ErrorCode.Type) => new AgentChannel.ChannelError({ code });
+const safe = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  code: typeof AgentChannel.ErrorCode.Type,
+): Effect.Effect<A, AgentChannel.ChannelError, R> =>
+  effect.pipe(
+    Effect.catchCause(cause =>
+      Cause.hasInterrupts(cause) ? Effect.interrupt : Effect.fail(fail(code)),
+    ),
+  );
+const AssetResultJson = Schema.Json.check(
+  Schema.makeFilter(
+    value => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 14_680_064,
+  ),
+);
+const Json = Schema.Json.check(
+  Schema.makeFilter(
+    value => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 2_097_152,
+  ),
+);
+const strict = { onExcessProperty: "error" } as const;
+const decode = <S extends Schema.Top>(
+  schema: S,
+  input: unknown,
+  code: typeof AgentChannel.ErrorCode.Type,
+) =>
+  safe(
+    Effect.suspend(() => Schema.decodeUnknownEffect(schema)(input, strict)),
+    code,
+  );
+const json = (value: unknown, code: typeof AgentChannel.ErrorCode.Type) =>
+  decode(Json, value, code);
+const decodeData = Effect.fn("AgentChannelRuntime.decodeData")(function* <S extends Schema.Top>(
+  schema: S,
+  input: unknown,
+  code: typeof AgentChannel.ErrorCode.Type,
+  largeAssetResult = false,
+) {
+  const boundary = largeAssetResult ? AssetResultJson : Json;
+  yield* decode(boundary, input, code);
+  const value = yield* decode(schema, input, code);
+  yield* decode(boundary, value, code);
+  return value;
+});
+
+const invokeHandler = (
+  handler: AgentChannel.Handler,
+  effect: Effect.Effect<unknown, unknown, unknown>,
+) =>
+  effect.pipe(
+    Effect.provideContext(handler.context),
+    Effect.catch(error =>
+      decode(
+        Schema.TaggedStruct("AgentChannelHandlerError", { code: AgentChannel.FailureCode }),
+        Predicate.isObject(error) ? { ...error } : error,
+        "provider_failure",
+      ).pipe(
+        Effect.flatMap(checked =>
+          Effect.fail(
+            new AgentChannel.ChannelError({ code: "provider_failure", providerCode: checked.code }),
+          ),
+        ),
+      ),
+    ),
+    Effect.catchCause(cause => {
+      if (Cause.hasInterrupts(cause)) return Effect.interrupt;
+      const error = Cause.findErrorOption(cause);
+      return Option.isSome(error) && error.value instanceof AgentChannel.ChannelError
+        ? Effect.fail(error.value)
+        : Effect.fail(fail("provider_failure"));
+    }),
+  );
+
+const checkExtensions = Effect.fn("AgentChannelRuntime.checkExtensions")(function* (
+  definition: AgentChannel.Definition,
+  extensions: Readonly<Record<string, Schema.Json>> | undefined,
+  code: typeof AgentChannel.ErrorCode.Type,
+) {
+  for (const [key, value] of Object.entries(extensions ?? {})) {
+    const schema = definition.extensions?.[key];
+    if (schema === undefined) return yield* fail(code);
+    // Extensions are checked values, not a provider payload escape hatch. No normalization.
+    yield* decodeData(Schema.toType(schema), value, code);
+  }
+});
+const checkMessage = (
+  features: AgentChannel.Features,
+  destination: AgentChannel.Destination,
+  content: AgentChannel.Content,
+): boolean =>
+  (destination.kind === "direct" || features.groups) &&
+  (destination.threadKey === undefined || features.threads) &&
+  (content.mentions === undefined || features.mentions) &&
+  (content.assets === undefined || features.assets) &&
+  (content.replyToMessageKey === undefined || features.replies);
+
+const checkDelivery = (
+  features: AgentChannel.Features,
+  command: Extract<AgentChannel.Command | AgentChannel.CommandV2, { kind: "deliver" }>,
+): boolean =>
+  "content" in command
+    ? checkMessage(features, command.destination, command.content)
+    : checkMessage(features, command.destination, { text: "" }) &&
+      (features.operations ?? []).includes(command.operation.kind);
+
+const Material = Schema.Struct({
+  connectionId: AgentChannel.Key,
+  // The plugin worker's resolver marks its JSON-carried material.
+  encoding: Schema.optionalKey(Schema.Literal("json")),
+  material: Schema.Unknown,
+  methodId: AgentChannel.Key,
+  providerId: AgentChannel.Key,
+  setup: Schema.Unknown,
+});
+const ResolveHook = Schema.declare(
+  (value): value is (material: unknown, context: { readonly setup: unknown }) => unknown =>
+    Predicate.isFunction(value),
+);
+const resolveAuth = Effect.fn("AgentChannelRuntime.resolveAuth")(function* (
+  providerId: string,
+  channelId: string,
+  definition: AgentChannel.Definition,
+  connectionId: string | undefined,
+  phase: string,
+  context: typeof ConnectionContext.Type | undefined,
+) {
+  if (definition.authMethods.length === 0) {
+    if (connectionId !== undefined) return yield* fail("invalid_auth");
+    return undefined;
+  }
+  // The host alone selects/authorizes the pinned connection. Its records never reach the plugin.
+  if (connectionId === undefined) return yield* fail("invalid_auth");
+  const resolver = yield* Effect.serviceOption(ConnectionResolver.Service);
+  if (Option.isNone(resolver)) return yield* fail("invalid_auth");
+  const raw = yield* safe(
+    Effect.suspend(() =>
+      resolver.value.resolve({
+        connectionId,
+        target: { phase, providerId, targetId: channelId, targetKind: "agent-channel" },
+        ...(context === undefined ? {} : { context }),
+      }),
+    ),
+    "invalid_auth",
+  );
+  const resolved = yield* decode(Material, raw, "invalid_auth");
+  if (resolved.providerId !== providerId || resolved.connectionId !== connectionId) {
+    return yield* fail("invalid_auth");
+  }
+  const method = definition.authMethods.find(
+    method =>
+      resolved.methodId === method.identifier ||
+      resolved.methodId === `${providerId}/${method.identifier}`,
+  );
+  if (method === undefined) return yield* fail("invalid_auth");
+  // Material the worker received as JSON decodes through each schema's JSON codec.
+  const decodeAuth = <S extends Schema.Top>(schema: S, value: unknown) =>
+    decode(
+      resolved.encoding === "json" ? Schema.toCodecJson(schema) : schema,
+      value,
+      "invalid_auth",
+    );
+  const setup =
+    method.setup === undefined
+      ? yield* decode(Schema.Undefined, resolved.setup, "invalid_auth")
+      : yield* decodeAuth(method.setup, resolved.setup);
+  const material = yield* decodeAuth(method.material, resolved.material);
+  let value: unknown;
+  if (method.resolve === undefined) {
+    value =
+      method.material === method.value
+        ? material
+        : yield* decode(method.value, material, "invalid_auth");
+  } else {
+    const hook = yield* decode(ResolveHook, method.resolve, "invalid_auth");
+    const output = yield* safe(
+      Effect.suspend(() => {
+        const result = hook(material, { setup });
+        return Effect.isEffect(result) ? result : Effect.succeed(result);
+      }),
+      "invalid_auth",
+    );
+    value = yield* decode(method.value, output, "invalid_auth");
+  }
+  // Schemas may use Redacted for auth. Only this checked value, never material/setup/binding,
+  // is exposed to the command handler.
+  return { methodId: method.identifier, value };
+});
+
+const find = (plugins: readonly Plugin.Any[], pin: Pin) => {
+  for (const provider of plugins) {
+    const channel = provider.agentChannels.find(
+      channel => `${provider.identifier}/${channel.identifier}` === pin.channelId,
+    );
+    if (channel !== undefined) return { definition: channel.definition, provider };
+  }
+  return undefined;
+};
+
+/** Build from the installed plugins. */
+export const layer = <P extends Plugin.Any>(
+  plugins: readonly P[],
+): Layer.Layer<Service, never, Requirements<P>> =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const context = yield* Effect.context<Requirements<P>>();
+      const get = Effect.fn("AgentChannelRuntime.get")(function* (input: unknown) {
+        const pin = yield* decode(Pin, input, "invalid_input");
+        const found = find(plugins, pin);
+        if (found === undefined) return yield* fail("not_found");
+        yield* safe(
+          Effect.sync(() => {
+            AgentChannel.validateDefinition(
+              found.definition,
+              found.provider.identifier,
+              found.provider.authMethods,
+            );
+          }),
+          "invalid_definition",
+        );
+        const handler = Option.fromNullishOr(
+          findHandler(
+            context,
+            found.provider.identifier,
+            AgentChannel.handlerKey(pin.channelId),
+          ) as AgentChannel.Handler | undefined,
+        );
+        if (
+          Option.isNone(handler) ||
+          !Predicate.isObject(handler.value.runtime) ||
+          !Predicate.isFunction(handler.value.runtime.execute) ||
+          !Predicate.isFunction(handler.value.runtime.verify) ||
+          !Predicate.isFunction(handler.value.runtime.checkAccess)
+        ) {
+          return yield* fail("handler_unavailable");
+        }
+        return found.definition;
+      });
+      const checkAccess = Effect.fn("AgentChannelRuntime.checkAccess")(function* (input: unknown) {
+        yield* json(input, "invalid_input");
+        const request = yield* decode(AccessInput, input, "invalid_input");
+        const definition = yield* get({ channelId: request.channelId });
+        const found = find(plugins, request);
+        if (found === undefined) return yield* fail("not_found");
+        const definitionSettings = yield* decodeData(
+          definition.definitionSettings,
+          request.definitionSettings,
+          "invalid_input",
+        );
+        const deploymentSettings = yield* decodeData(
+          definition.deploymentSettings,
+          request.deploymentSettings,
+          "invalid_input",
+        );
+        if (!checkMessage(definition.features, request.identity.conversation, { text: "" })) {
+          return yield* fail("unsupported_feature");
+        }
+        const auth = yield* resolveAuth(
+          found.provider.identifier,
+          request.channelId,
+          definition,
+          request.connectionId,
+          "check_access",
+          request.context,
+        );
+        const handler = Option.fromNullishOr(
+          findHandler(
+            context,
+            found.provider.identifier,
+            AgentChannel.handlerKey(request.channelId),
+          ) as AgentChannel.Handler | undefined,
+        );
+        if (Option.isNone(handler)) return yield* fail("handler_unavailable");
+        const output = yield* invokeHandler(
+          handler.value,
+          Effect.suspend(() =>
+            handler.value.runtime.checkAccess(request.identity, {
+              definitionSettings,
+              deploymentSettings,
+              ...(auth === undefined ? {} : { auth }),
+            }),
+          ),
+        );
+        return yield* decodeData(AgentChannel.AccessOutcome, output, "invalid_result");
+      });
+      const execute = Effect.fn("AgentChannelRuntime.execute")(function* (input: unknown) {
+        yield* json(input, "invalid_input");
+        const request = yield* decode(Input, input, "invalid_input");
+        const definition = yield* get({ channelId: request.channelId });
+        const found = find(plugins, request);
+        if (found === undefined) return yield* fail("not_found");
+        const definitionSettings = yield* decodeData(
+          definition.definitionSettings,
+          request.definitionSettings,
+          "invalid_input",
+        );
+        const deploymentSettings = yield* decodeData(
+          definition.deploymentSettings,
+          request.deploymentSettings,
+          "invalid_input",
+        );
+        const schemas = AgentChannel.schemasFor(definition);
+        const command: AgentChannel.Command | AgentChannel.CommandV2 = yield* decodeData(
+          schemas.command,
+          request.command,
+          "invalid_input",
+        );
+        yield* checkExtensions(definition, command.extensions, "invalid_input");
+        if (command.kind === "deliver" && command.operationKey !== command.deliveryKey) {
+          return yield* fail("invalid_input");
+        }
+        if (command.kind === "deliver" && !checkDelivery(definition.features, command)) {
+          return yield* fail("unsupported_feature");
+        }
+        if (
+          command.kind === "deliver" &&
+          "operation" in command &&
+          command.operation.kind === "set_reaction" &&
+          command.operation.target.kind === "activation" &&
+          command.activationMessageKey === undefined
+        ) {
+          return yield* fail("invalid_input");
+        }
+        if (
+          command.kind === "read_context" &&
+          (definition.features.readContext !== true ||
+            !checkMessage(definition.features, command.destination, { text: "" }))
+        ) {
+          return yield* fail("unsupported_feature");
+        }
+        const handler = Option.fromNullishOr(
+          findHandler(
+            context,
+            found.provider.identifier,
+            AgentChannel.handlerKey(request.channelId),
+          ) as AgentChannel.Handler | undefined,
+        );
+        if (Option.isNone(handler)) return yield* fail("handler_unavailable");
+        const auth = yield* resolveAuth(
+          found.provider.identifier,
+          request.channelId,
+          definition,
+          request.connectionId,
+          command.kind,
+          request.context,
+        );
+        // Keep correlation facts independent of any mutation by provider code.
+        const operationKey = command.operationKey;
+        const kind = command.kind;
+        const deliveryKey = command.kind === "deliver" ? command.deliveryKey : undefined;
+        const assetKey = command.kind === "read_asset" ? command.asset.assetKey : undefined;
+        const adapterContext = {
+          definitionSettings,
+          deploymentSettings,
+          ...(auth === undefined ? {} : { auth }),
+        };
+        if (
+          !Predicate.isFunction(handler.value.runtime.execute) ||
+          !Predicate.isFunction(handler.value.runtime.verify) ||
+          !Predicate.isFunction(handler.value.runtime.checkAccess)
+        ) {
+          return yield* fail("handler_unavailable");
+        }
+        if (command.kind === "receive") {
+          yield* decodeData(
+            AgentChannel.Verification,
+            yield* invokeHandler(
+              handler.value,
+              Effect.suspend(() => handler.value.runtime.verify(command.request, adapterContext)),
+            ),
+            "invalid_result",
+          );
+        }
+        if (command.kind === "read_asset") {
+          if (!definition.features.assets) return yield* fail("unsupported_feature");
+          const decision = yield* decodeData(
+            AgentChannel.AccessOutcome,
+            yield* invokeHandler(
+              handler.value,
+              Effect.suspend(() =>
+                handler.value.runtime.checkAccess(command.identity, adapterContext),
+              ),
+            ),
+            "invalid_result",
+          );
+          if (decision.decision !== "allow") {
+            return yield* new AgentChannel.ChannelError({
+              code: "provider_failure",
+              providerCode: "unauthorized",
+            });
+          }
+        }
+        const output = yield* invokeHandler(
+          handler.value,
+          Effect.suspend(() => handler.value.runtime.execute(command, adapterContext)),
+        );
+        const result: AgentChannel.Result | AgentChannel.ResultV2 = yield* decodeData(
+          schemas.typeResult,
+          output,
+          "invalid_result",
+          kind === "read_asset",
+        );
+        if (
+          result.kind !== kind ||
+          result.operationKey !== operationKey ||
+          (result.kind === "deliver" && result.deliveryKey !== deliveryKey) ||
+          (result.kind === "read_asset" && result.assetKey !== assetKey)
+        ) {
+          return yield* fail("invalid_result");
+        }
+        yield* checkExtensions(definition, result.extensions, "invalid_result");
+        if (
+          result.kind === "deliver" &&
+          result.status === "pending" &&
+          !definition.features.deliveryState
+        ) {
+          return yield* fail("invalid_result");
+        }
+        const allowedEvents: AgentChannel.EventV2[] = [];
+        const deniedEventKeys: string[] = [];
+        if (result.kind === "receive") {
+          if (result.deniedEventKeys !== undefined) return yield* fail("invalid_result");
+          if (
+            result.activationProof === "verified" &&
+            (result.response === undefined || result.events.length !== 0)
+          ) {
+            return yield* fail("invalid_result");
+          }
+          const eventKeys = new Set<string>();
+          for (const event of result.events) {
+            if (eventKeys.has(event.eventKey)) return yield* fail("invalid_result");
+            eventKeys.add(event.eventKey);
+            if (
+              event.kind === "message" &&
+              !checkMessage(definition.features, event.conversation, event.content)
+            ) {
+              return yield* fail("invalid_result");
+            }
+            if (
+              (event.kind === "echo" || event.kind === "stop") &&
+              !checkMessage(definition.features, event.conversation, { text: "" })
+            ) {
+              return yield* fail("invalid_result");
+            }
+            if (event.kind === "delivery_update" && !definition.features.deliveryState) {
+              return yield* fail("invalid_result");
+            }
+            yield* checkExtensions(definition, event.extensions, "invalid_result");
+            let denied = false;
+            if (event.kind === "message" || event.kind === "echo" || event.kind === "stop") {
+              const identity = yield* decodeData(
+                AgentChannel.VerifiedIdentity,
+                { conversation: event.conversation, senderKey: event.senderKey },
+                "invalid_result",
+              );
+              const decision = yield* decodeData(
+                AgentChannel.AccessOutcome,
+                yield* invokeHandler(
+                  handler.value,
+                  Effect.suspend(() => handler.value.runtime.checkAccess(identity, adapterContext)),
+                ),
+                "invalid_result",
+              );
+              denied = decision.decision === "deny";
+            }
+            if (denied) {
+              deniedEventKeys.push(event.eventKey);
+              continue;
+            }
+            allowedEvents.push(event);
+          }
+        }
+        // Store the encoded state so subsequent pinned commands can decode it exactly once.
+        const encoded = yield* safe(
+          Schema.encodeUnknownEffect(schemas.result)(
+            result.kind === "receive"
+              ? {
+                  ...result,
+                  events: allowedEvents,
+                  ...(deniedEventKeys.length === 0 ? {} : { deniedEventKeys }),
+                }
+              : result,
+            strict,
+          ),
+          "invalid_result",
+        );
+        return yield* decodeData(
+          AgentChannel.CheckedResult,
+          encoded,
+          "invalid_result",
+          kind === "read_asset",
+        );
+      });
+      // SAFETY: Requirements above account for each schema, auth method and Channel handler. The
+      // dynamic lookup erases their union; the captured application context discharges it here.
+      const run = <A>(
+        effect: Effect.Effect<A, AgentChannel.ChannelError, unknown>,
+      ): Effect.Effect<A, AgentChannel.ChannelError> =>
+        // @effect-diagnostics-next-line unsafeEffectTypeAssertion:off -- Channel handlers are checked and their captured context satisfies the declared Requirements (SAFETY above).
+        effect.pipe(Effect.provideContext(context)) as Effect.Effect<A, AgentChannel.ChannelError>;
+      const decodeSettings = (field: "definitionSettings" | "deploymentSettings") =>
+        Effect.fn("AgentChannelRuntime.decodeSettings")(function* (input: unknown) {
+          const request = yield* decode(
+            Schema.Struct({ ...Pin.fields, value: Schema.Json }),
+            input,
+            "invalid_input",
+          );
+          const definition = yield* get({ channelId: request.channelId });
+          const schema = definition[field];
+          const value = yield* decodeData(schema, request.value, "invalid_input");
+          return yield* json(
+            yield* safe(Schema.encodeUnknownEffect(schema)(value, strict), "invalid_input"),
+            "invalid_input",
+          );
+        });
+      return Service.of({
+        checkAccess: input => run(checkAccess(input)),
+        decodeDefinitionSettings: input => run(decodeSettings("definitionSettings")(input)),
+        decodeDeploymentSettings: input => run(decodeSettings("deploymentSettings")(input)),
+        execute: input => run(execute(input)),
+        get: input => run(get(input)),
+      });
+    }),
+  );
+
+export * as AgentChannelRuntime from "./AgentChannelRuntime.ts";