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

package/src/AgentChannel.ts

@@ -0,0 +1,860 @@
+/** Provider-neutral external Agent Channel contracts. @since 0.0.0 */
+import type { Context, Effect, Pipeable, SchemaAST } from "effect";
+import { Match, Predicate, Schema } from "effect";
+
+import * as AuthMethod from "./AuthMethod.ts";
+import { validateIdentifier } from "./internal/identifier.ts";
+import { PipeableProto } from "./internal/proto.ts";
+import * as ToolFile from "./ToolFile.ts";
+
+export const TypeId = "@dual-os/sdk/AgentChannel" as const;
+export type TypeId = typeof TypeId;
+
+/** Keys are opaque and installation-scoped. Never parse them into product identities. */
+export const Key = Schema.NonEmptyString.check(
+  Schema.isMaxLength(512),
+  Schema.isPattern(/^[^\p{Cc}]+$/u),
+);
+/**
+ * The command and result schemas a version uses. Absent means the original protocol, whose
+ * projection stays byte-identical for contracts already published with it. `v2` adds the stop
+ * event, conversation reads and output operations.
+ */
+export const Protocol = Schema.Literals(["v2"]);
+export type Protocol = typeof Protocol.Type;
+/** What a `v2` destination can show. Every channel shows `present_outcome`. */
+export const OperationKind = Schema.Literals([
+  "present_outcome",
+  "create_message",
+  "update_message",
+  "delete_message",
+  "set_reaction",
+  "set_activity",
+  "render_plan",
+]);
+export type OperationKind = typeof OperationKind.Type;
+export const Features = Schema.Struct({
+  assets: Schema.Boolean,
+  /** Whether replaying one durable delivery key is safe at the provider boundary. */
+  deliveryMode: Schema.Literals(["idempotent", "at-most-once"]),
+  deliveryState: Schema.Boolean,
+  directText: Schema.Literal(true),
+  groups: Schema.Boolean,
+  /** Maximum Unicode code points per physical text message, including server-added prefixes. */
+  maxTextLength: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
+  mentions: Schema.Boolean,
+  /** `v2` only: the output operations every destination of this version shows. */
+  operations: Schema.optionalKey(Schema.Array(OperationKind)),
+  /** `v2` only: whether `read_context` returns the conversation's earlier messages. */
+  readContext: Schema.optionalKey(Schema.Boolean),
+  replies: Schema.Boolean,
+  /** Maximum age of the original responding input before preparation and delivery. */
+  responseWindowMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
+  threads: Schema.Boolean,
+});
+export type Features = typeof Features.Type;
+
+const HttpUrl = Schema.String.check(
+  Schema.isMaxLength(8192),
+  Schema.makeFilter(value => {
+    const url = URL.parse(value);
+    return (
+      url !== null &&
+      (url.protocol === "https:" || url.protocol === "http:") &&
+      url.username === "" &&
+      url.password === ""
+    );
+  }),
+);
+const Text = Schema.String.check(Schema.isMaxLength(65_536));
+const ExtensionKey = Schema.String.check(
+  Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/),
+);
+const Extensions = Schema.Record(Schema.String, Schema.Json).check(
+  Schema.makeFilter(values => Object.keys(values).every(Schema.is(ExtensionKey))),
+);
+export const Destination = Schema.Struct({
+  conversationKey: Key,
+  kind: Schema.Literals(["direct", "group"]),
+  threadKey: Schema.optionalKey(Key),
+});
+export type Destination = typeof Destination.Type;
+export const Asset = Schema.Struct({
+  assetKey: Key,
+  mediaType: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+  url: HttpUrl,
+});
+export const Content = Schema.Struct({
+  assets: Schema.optionalKey(Schema.Array(Asset).check(Schema.isMaxLength(20))),
+  mentions: Schema.optionalKey(Schema.Array(Key).check(Schema.isMaxLength(100))),
+  replyToMessageKey: Schema.optionalKey(Key),
+  text: Text,
+}).check(
+  Schema.makeFilter(content => content.text.length > 0 || (content.assets?.length ?? 0) > 0),
+);
+export type Content = typeof Content.Type;
+
+/** The body is the unmodified UTF-8 provider body, before JSON parsing/signature verification. */
+export const Request = Schema.Struct({
+  body: Schema.String.check(
+    Schema.isMaxLength(1_048_576),
+    Schema.makeFilter(body => new TextEncoder().encode(body).byteLength <= 1_048_576),
+  ),
+  headers: Schema.Record(
+    Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+    Schema.String.check(Schema.isMaxLength(8192)),
+  ),
+  method: Schema.Literals(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  url: HttpUrl,
+});
+export type Request = typeof Request.Type;
+const ResponseHeaders = Schema.Record(
+  Schema.NonEmptyString.check(Schema.isMaxLength(256), Schema.isPattern(/^[a-z0-9-]+$/)),
+  Schema.String.check(Schema.isMaxLength(8192)),
+).check(
+  Schema.makeFilter(headers =>
+    Object.keys(headers).every(name => name === "content-type" || name === "cache-control"),
+  ),
+);
+/** Bounded provider-required webhook response, returned only after request verification. */
+export const WebhookResponse = Schema.Struct({
+  body: Schema.String.check(
+    Schema.isMaxLength(65_536),
+    Schema.makeFilter(body => new TextEncoder().encode(body).byteLength <= 65_536),
+  ),
+  headers: Schema.optionalKey(ResponseHeaders),
+  status: Schema.Int.check(Schema.isBetween({ maximum: 299, minimum: 200 })),
+});
+export type WebhookResponse = typeof WebhookResponse.Type;
+export const Timestamp = Schema.String.check(
+  Schema.isMaxLength(64),
+  Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/),
+  Schema.makeFilter(value => {
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = month === 2 ? (leap ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31;
+    return (
+      month >= 1 &&
+      month <= 12 &&
+      day >= 1 &&
+      day <= days &&
+      Number(value.slice(11, 13)) < 24 &&
+      Number(value.slice(14, 16)) < 60 &&
+      Number(value.slice(17, 19)) < 60 &&
+      Schema.decodeUnknownExit(Schema.DateTimeUtcFromString)(value)._tag === "Success"
+    );
+  }),
+);
+export const VerifiedIdentity = Schema.Struct({ conversation: Destination, senderKey: Key });
+export type VerifiedIdentity = typeof VerifiedIdentity.Type;
+export const AccessOutcome = Schema.Struct({ decision: Schema.Literals(["allow", "deny"]) });
+export type AccessOutcome = typeof AccessOutcome.Type;
+export const Verification = Schema.Struct({ verified: Schema.Literal(true) });
+export type Verification = typeof Verification.Type;
+export const Exposure = Schema.Literals(["webhook", "host"]);
+export const RequiredChecks = Schema.Tuple([Schema.Literal("access")]);
+export const Message = Schema.Struct({
+  content: Content,
+  conversation: Destination,
+  eventKey: Key,
+  extensions: Schema.optionalKey(Extensions),
+  kind: Schema.Literal("message"),
+  messageKey: Key,
+  respond: Schema.Boolean,
+  senderKey: Key,
+  timestamp: Timestamp,
+});
+export const DeliveryUpdate = Schema.Struct({
+  deliveryKey: Key,
+  deliveryUpdateKey: Key,
+  eventKey: Key,
+  extensions: Schema.optionalKey(Extensions),
+  kind: Schema.Literal("delivery_update"),
+  providerDeliveryKey: Key,
+  sequence: Schema.Natural,
+  status: Schema.Literals(["succeeded", "failed"]),
+  timestamp: Timestamp,
+});
+/** Provider-confirmed own output. No content is accepted or added to conversation history. */
+export const Echo = Schema.Struct({
+  ...VerifiedIdentity.fields,
+  eventKey: Key,
+  extensions: Schema.optionalKey(Extensions),
+  kind: Schema.Literal("echo"),
+  messageKey: Key,
+  timestamp: Timestamp,
+});
+export const Event = Schema.Union([Message, Echo, DeliveryUpdate]);
+export type Event = typeof Event.Type;
+/** `v2`: the sender asked the agent to stop working in this conversation. Access applies. */
+export const Stop = Schema.Struct({
+  ...VerifiedIdentity.fields,
+  eventKey: Key,
+  extensions: Schema.optionalKey(Extensions),
+  kind: Schema.Literal("stop"),
+  timestamp: Timestamp,
+});
+export const EventV2 = Schema.Union([Message, Echo, DeliveryUpdate, Stop]);
+export type EventV2 = typeof EventV2.Type;
+
+/** The reactions every `v2` provider can show. Each provider maps them to its own emoji. */
+export const Reaction = Schema.Literals([
+  "thumbs_up",
+  "thumbs_down",
+  "laugh",
+  "confused",
+  "heart",
+  "hooray",
+  "rocket",
+  "eyes",
+]);
+export type Reaction = typeof Reaction.Type;
+const ShortText = Schema.NonEmptyString.check(Schema.isMaxLength(200));
+export const PlanItem = Schema.Struct({
+  itemKey: Key,
+  note: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(2000))),
+  state: Schema.Literals(["pending", "in_progress", "completed", "failed"]),
+  title: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
+});
+/** A whole task list, always sent complete. Item keys are unique and stable across revisions. */
+export const Plan = Schema.Struct({
+  items: Schema.Array(PlanItem).check(
+    Schema.isMaxLength(50),
+    Schema.makeFilter(items => new Set(items.map(item => item.itemKey)).size === items.length),
+  ),
+  title: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(256))),
+});
+export type Plan = typeof Plan.Type;
+/**
+ * One piece of `v2` output. A `reference` is the `providerDeliveryKey` the provider returned for
+ * the message or plan it made; only that provider reads it.
+ */
+export const Operation = Schema.Union([
+  /**
+   * End the turn. `awaiting_input` ends it with a question, optionally with choices. The
+   * provider clears any activity it shows. Earlier parts of a long text arrive as
+   * `create_message` operations.
+   */
+  Schema.Struct({
+    kind: Schema.Literal("present_outcome"),
+    options: Schema.optionalKey(Schema.Array(ShortText).check(Schema.isMaxLength(10))),
+    outcome: Schema.Literals(["completed", "failed", "awaiting_input"]),
+    text: Text,
+  }).check(
+    Schema.makeFilter(
+      operation => operation.options === undefined || operation.outcome === "awaiting_input",
+    ),
+  ),
+  Schema.Struct({
+    kind: Schema.Literal("create_message"),
+    messageKey: Key,
+    text: Text.check(Schema.isMinLength(1)),
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("update_message"),
+    messageKey: Key,
+    reference: Key,
+    text: Text.check(Schema.isMinLength(1)),
+  }),
+  Schema.Struct({ kind: Schema.Literal("delete_message"), messageKey: Key, reference: Key }),
+  /** Make the agent's reaction present (`active`) or absent. Desired state: repeating is safe. */
+  Schema.Struct({
+    active: Schema.Boolean,
+    kind: Schema.Literal("set_reaction"),
+    reaction: Reaction,
+    target: Schema.Union([
+      /** The message that started the turn: `activationMessageKey` of the command. */
+      Schema.Struct({ kind: Schema.Literal("activation") }),
+      Schema.Struct({ kind: Schema.Literal("message"), reference: Key }),
+    ]),
+  }),
+  /** What the agent is doing now, such as a typing indicator or a status line. Latest wins. */
+  Schema.Struct({
+    activity: Schema.Union([
+      Schema.Struct({ kind: Schema.Literal("working"), text: Schema.optionalKey(ShortText) }),
+      Schema.Struct({ kind: Schema.Literal("idle") }),
+    ]),
+    kind: Schema.Literal("set_activity"),
+  }),
+  /** Show this revision of the plan, replacing the one at `reference` when there is one. */
+  Schema.Struct({
+    kind: Schema.Literal("render_plan"),
+    plan: Plan,
+    reference: Schema.optionalKey(Key),
+    revision: Schema.Int.check(Schema.isGreaterThan(0)),
+  }),
+]);
+export type Operation = typeof Operation.Type;
+/** A message read back from the provider's conversation history. */
+export const ContextMessage = Schema.Struct({
+  messageKey: Key,
+  /** The agent's own message. */
+  own: Schema.Boolean,
+  senderKey: Key,
+  senderName: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(256))),
+  text: Text,
+  timestamp: Timestamp,
+});
+export type ContextMessage = typeof ContextMessage.Type;
+/** Decoded originals are limited separately by the host; ordinary command JSON stays bounded. */
+export const AssetFile = ToolFile.Schema.check(
+  Schema.makeFilter(
+    file =>
+      file.sizeBytes > 0 && file.sizeBytes <= 10_485_760 && file.contentBase64.length <= 13_981_016,
+  ),
+);
+
+/** Closed error vocabulary: provider messages, payloads, and causes never cross this seam. */
+export const FailureCode = Schema.Literals([
+  "rejected",
+  "unauthorized",
+  "rate_limited",
+  "unavailable",
+  "unknown_completion",
+  /** The provider definitely refused this send because its delivery window was closed. */
+  "window_closed",
+]);
+export class HandlerError extends Schema.TaggedError<HandlerError>()("AgentChannelHandlerError", {
+  code: FailureCode,
+}) {}
+export const ErrorCode = Schema.Literals([
+  "invalid_definition",
+  "not_found",
+  "invalid_input",
+  "invalid_auth",
+  "unsupported_feature",
+  "invalid_result",
+  "handler_unavailable",
+  "provider_failure",
+]);
+export class ChannelError extends Schema.TaggedError<ChannelError>()("AgentChannelError", {
+  code: ErrorCode,
+  providerCode: Schema.optionalKey(FailureCode),
+}) {
+  override get message(): string {
+    return `Agent Channel ${this.code}`;
+  }
+}
+
+const installedCommandSchema = <State extends Schema.Top>(state: State) => {
+  const operation = { extensions: Schema.optionalKey(Extensions), operationKey: Key };
+  const installed = { ...operation, installationKey: Key, state };
+  return Schema.Union([
+    Schema.Struct({
+      kind: Schema.Literal("activate"),
+      ...operation,
+      ingressUrl: HttpUrl,
+      state: Schema.optionalKey(state),
+    }),
+    Schema.Struct({ kind: Schema.Literal("deactivate"), ...installed }),
+    Schema.Struct({ kind: Schema.Literal("receive"), ...installed, request: Request }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...installed,
+      deliveryKey: Key,
+      destination: Destination,
+      content: Content,
+      /** Original responding input timestamp; retries must preserve this reference. */
+      responseToTimestamp: Schema.optionalKey(Timestamp),
+    }),
+  ]);
+};
+
+const installedCommandSchemaV2 = <State extends Schema.Top>(state: State) => {
+  const operation = { extensions: Schema.optionalKey(Extensions), operationKey: Key };
+  const installed = { ...operation, installationKey: Key, state };
+  return Schema.Union([
+    Schema.Struct({
+      kind: Schema.Literal("activate"),
+      ...operation,
+      ingressUrl: HttpUrl,
+      state: Schema.optionalKey(state),
+    }),
+    Schema.Struct({ kind: Schema.Literal("deactivate"), ...installed }),
+    Schema.Struct({ kind: Schema.Literal("receive"), ...installed, request: Request }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...installed,
+      /** The provider message that started the turn, when the host knows it. */
+      activationMessageKey: Schema.optionalKey(Key),
+      deliveryKey: Key,
+      destination: Destination,
+      operation: Operation,
+      /** Original responding input timestamp; retries must preserve this reference. */
+      responseToTimestamp: Schema.optionalKey(Timestamp),
+    }),
+    /** The conversation's latest messages, oldest first, at most `limit`. */
+    Schema.Struct({
+      kind: Schema.Literal("read_context"),
+      ...installed,
+      destination: Destination,
+      limit: Schema.Int.check(Schema.isBetween({ maximum: 200, minimum: 1 })),
+    }),
+  ]);
+};
+
+const installedResultSchema = <State extends Schema.Top>(state: State) => {
+  const operation = { extensions: Schema.optionalKey(Extensions), operationKey: Key };
+  return Schema.Union([
+    Schema.Struct({
+      kind: Schema.Literal("activate"),
+      ...operation,
+      installationKey: Key,
+      state,
+      /** Durable read-only provider state that the host must persist before retrying activation. */
+      checkpoint: Schema.optionalKey(Schema.Literal(true)),
+      /** The host must observe a verified webhook handshake before cutover. */
+      verification: Schema.optionalKey(Schema.Literal("ingress")),
+    }),
+    Schema.Struct({ kind: Schema.Literal("deactivate"), ...operation }),
+    Schema.Struct({
+      kind: Schema.Literal("receive"),
+      ...operation,
+      verified: Schema.Literal(true),
+      deniedEventKeys: Schema.optionalKey(Schema.Array(Key).check(Schema.isMaxLength(100))),
+      events: Schema.Array(Event).check(Schema.isMaxLength(100)),
+      response: Schema.optionalKey(WebhookResponse),
+      /** A provider-native setup challenge or ping proved the configured ingress. */
+      activationProof: Schema.optionalKey(Schema.Literal("verified")),
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("succeeded"),
+      providerDeliveryKey: Key,
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("pending"),
+      providerDeliveryKey: Key,
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("failed"),
+      code: Schema.Literals([
+        "rejected",
+        "unauthorized",
+        "rate_limited",
+        "unavailable",
+        "window_closed",
+      ]),
+    }),
+  ]);
+};
+// `v2` keeps every `v1` result except `receive`, which also carries stop events.
+const installedResultSchemaV2 = <State extends Schema.Top>(state: State) => {
+  const operation = { extensions: Schema.optionalKey(Extensions), operationKey: Key };
+  return Schema.Union([
+    Schema.Struct({
+      kind: Schema.Literal("activate"),
+      ...operation,
+      installationKey: Key,
+      state,
+      /** Durable read-only provider state that the host must persist before retrying activation. */
+      checkpoint: Schema.optionalKey(Schema.Literal(true)),
+      /** The host must observe a verified webhook handshake before cutover. */
+      verification: Schema.optionalKey(Schema.Literal("ingress")),
+    }),
+    Schema.Struct({ kind: Schema.Literal("deactivate"), ...operation }),
+    Schema.Struct({
+      kind: Schema.Literal("receive"),
+      ...operation,
+      verified: Schema.Literal(true),
+      deniedEventKeys: Schema.optionalKey(Schema.Array(Key).check(Schema.isMaxLength(100))),
+      events: Schema.Array(EventV2).check(Schema.isMaxLength(100)),
+      response: Schema.optionalKey(WebhookResponse),
+      /** A provider-native setup challenge or ping proved the configured ingress. */
+      activationProof: Schema.optionalKey(Schema.Literal("verified")),
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("succeeded"),
+      providerDeliveryKey: Key,
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("pending"),
+      providerDeliveryKey: Key,
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("deliver"),
+      ...operation,
+      deliveryKey: Key,
+      status: Schema.Literal("failed"),
+      code: Schema.Literals([
+        "rejected",
+        "unauthorized",
+        "rate_limited",
+        "unavailable",
+        "window_closed",
+      ]),
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("read_context"),
+      ...operation,
+      messages: Schema.Array(ContextMessage).check(Schema.isMaxLength(200)),
+    }),
+  ]);
+};
+const readAssetCommand = <State extends Schema.Top>(state: State) =>
+  Schema.Struct({
+    asset: Asset,
+    extensions: Schema.optionalKey(Extensions),
+    identity: VerifiedIdentity,
+    installationKey: Key,
+    kind: Schema.Literal("read_asset"),
+    operationKey: Key,
+    state,
+  });
+const readAssetResult = Schema.Struct({
+  assetKey: Key,
+  extensions: Schema.optionalKey(Extensions),
+  file: AssetFile,
+  kind: Schema.Literal("read_asset"),
+  operationKey: Key,
+});
+export const commandSchema = <State extends Schema.Top>(state: State) =>
+  Schema.Union([installedCommandSchema(state), readAssetCommand(state)]);
+export const resultSchema = <State extends Schema.Top>(state: State) =>
+  Schema.Union([installedResultSchema(state), readAssetResult]);
+export const commandSchemaV2 = <State extends Schema.Top>(state: State) =>
+  Schema.Union([installedCommandSchemaV2(state), readAssetCommand(state)]);
+export const resultSchemaV2 = <State extends Schema.Top>(state: State) =>
+  Schema.Union([installedResultSchemaV2(state), readAssetResult]);
+export type Command<State extends Schema.Top = Schema.Unknown> = ReturnType<
+  typeof commandSchema<State>
+>["Type"];
+export type Result<State extends Schema.Top = Schema.Unknown> = ReturnType<
+  typeof resultSchema<State>
+>["Type"];
+export type CommandV2<State extends Schema.Top = Schema.Unknown> = ReturnType<
+  typeof commandSchemaV2<State>
+>["Type"];
+export type ResultV2<State extends Schema.Top = Schema.Unknown> = ReturnType<
+  typeof resultSchemaV2<State>
+>["Type"];
+/** The command and result schemas of a Channel's protocol. */
+export const schemasFor = (definition: Pick<Definition, "protocol" | "state">) =>
+  definition.protocol === "v2"
+    ? {
+        command: commandSchemaV2(definition.state),
+        result: resultSchemaV2(definition.state),
+        typeResult: resultSchemaV2(Schema.toType(definition.state)),
+      }
+    : {
+        command: commandSchema(definition.state),
+        result: resultSchema(definition.state),
+        typeResult: resultSchema(Schema.toType(definition.state)),
+      };
+
+/**
+ * Encoded, JSON-safe runtime result suitable for host persistence. It accepts both protocols;
+ * a `v1` result decodes unchanged.
+ */
+export const CheckedResult = resultSchemaV2(Schema.Json);
+export type CheckedResult = typeof CheckedResult.Type;
+
+/** Immutable catalog projection. Live schemas remain the execution validators. */
+export const Contract = Schema.Struct({
+  definitionSettingsSchemaJson: Schema.Json,
+  deploymentSettingsSchemaJson: Schema.Json,
+  exposure: Exposure,
+  extensionsSchemaJson: Schema.Record(Schema.String, Schema.Json),
+  featuresJson: Features,
+  operationInputSchemaJson: Schema.Json,
+  operationOutputSchemaJson: Schema.Json,
+  protocol: Schema.optionalKey(Protocol),
+  requiredChecks: RequiredChecks,
+  stateSchemaJson: Schema.Json,
+});
+export type Contract = typeof Contract.Type;
+
+export interface Definition<
+  Settings extends Schema.Top = Schema.Top,
+  Mappings extends Schema.Top = Schema.Top,
+  State extends Schema.Top = Schema.Top,
+  Methods extends readonly AuthMethod.Any[] = readonly AuthMethod.Any[],
+> {
+  /** Absent for the original protocol. Publish a new release to change it. */
+  readonly protocol?: Protocol;
+  readonly definitionSettings: Settings;
+  readonly deploymentSettings: Mappings;
+  readonly state: State;
+  readonly features: Features;
+  readonly exposure: typeof Exposure.Type;
+  readonly requiredChecks: typeof RequiredChecks.Type;
+  /** Explicit subset of the provider's methods; [] means the channel accepts no connection. */
+  readonly authMethods: Methods;
+  /** Each key is provider/name. Values are checked on every command/result/event. */
+  readonly extensions?: Readonly<Record<string, Schema.Top>>;
+}
+/** Project the exact declaration once for SDK discovery and server contract comparison. */
+export const projectContract = (
+  definition: Definition,
+  project: (schema: Schema.Top) => unknown = schema =>
+    Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" }),
+): Contract => {
+  const schemas = schemasFor(definition);
+  return Schema.decodeUnknownSync(Contract)(
+    {
+      definitionSettingsSchemaJson: project(definition.definitionSettings),
+      deploymentSettingsSchemaJson: project(definition.deploymentSettings),
+      exposure: definition.exposure,
+      extensionsSchemaJson: Object.fromEntries(
+        Object.entries(definition.extensions ?? {}).map(([key, schema]) => [key, project(schema)]),
+      ),
+      featuresJson: definition.features,
+      operationInputSchemaJson: project(schemas.command),
+      operationOutputSchemaJson: project(schemas.result),
+      ...(definition.protocol === undefined ? {} : { protocol: definition.protocol }),
+      requiredChecks: definition.requiredChecks,
+      stateSchemaJson: project(definition.state),
+    },
+    { onExcessProperty: "error" },
+  );
+};
+export interface Any extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+  readonly identifier: string;
+  readonly name: string | undefined;
+  readonly description: string | undefined;
+  readonly definition: Definition;
+}
+export interface AgentChannel<
+  out Identifier extends string = string,
+  out D extends Definition = Definition,
+> extends Any {
+  readonly identifier: Identifier;
+  readonly definition: D;
+}
+export type ResolvedAuth<Methods extends readonly AuthMethod.Any[]> =
+  Methods[number] extends infer M
+    ? M extends AuthMethod.Any
+      ? { readonly methodId: M["identifier"]; readonly value: AuthMethod.Value<M> }
+      : never
+    : never;
+export type HandlerContext<D extends Definition> = {
+  readonly definitionSettings: D["definitionSettings"]["Type"];
+  readonly deploymentSettings: D["deploymentSettings"]["Type"];
+} & (D["authMethods"] extends readonly []
+  ? {}
+  : number extends D["authMethods"]["length"]
+    ? { readonly auth?: ResolvedAuth<D["authMethods"]> }
+    : { readonly auth: ResolvedAuth<D["authMethods"]> });
+/** The command a Channel's handler receives, by its protocol. */
+export type CommandFor<D extends Definition> = D extends { readonly protocol: "v2" }
+  ? CommandV2<D["state"]>
+  : Command<D["state"]>;
+/** The result a Channel's handler returns, by its protocol. */
+export type ResultFor<D extends Definition> = D extends { readonly protocol: "v2" }
+  ? ResultV2<D["state"]>
+  : Result<D["state"]>;
+export interface RuntimeContract<D extends Definition, R = never> {
+  readonly verify: (
+    request: Request,
+    context: HandlerContext<D>,
+  ) => Effect.Effect<Verification, HandlerError, R>;
+  readonly checkAccess: (
+    identity: VerifiedIdentity,
+    context: HandlerContext<D>,
+  ) => Effect.Effect<AccessOutcome, HandlerError, R>;
+  readonly execute: (
+    command: CommandFor<D>,
+    context: HandlerContext<D>,
+  ) => Effect.Effect<ResultFor<D>, HandlerError, R>;
+}
+/** Erased service representation. Input and output are checked by AgentChannelRuntime. */
+export interface Handler<Id extends string = string> {
+  readonly channelId: Id;
+  readonly context: Context.Context<never>;
+  readonly runtime: {
+    readonly verify: (
+      request: unknown,
+      context: unknown,
+    ) => Effect.Effect<unknown, unknown, unknown>;
+    readonly checkAccess: (
+      identity: unknown,
+      context: unknown,
+    ) => Effect.Effect<unknown, unknown, unknown>;
+    readonly execute: (
+      command: unknown,
+      context: unknown,
+    ) => Effect.Effect<unknown, unknown, unknown>;
+  };
+}
+export const handlerKey = (channelId: string): string =>
+  `@dual-os/sdk/AgentChannel/Handler/${channelId}`;
+
+const SchemaDefinition = Schema.declare(Schema.isSchema);
+// Fail closed on holes such as Unknown nested inside an otherwise typed state schema.
+const checkSchema = (schema: Schema.Top, allowOpaque = false): void => {
+  const seen = new Set<SchemaAST.AST>();
+  const visit = (ast: SchemaAST.AST): void => {
+    if (seen.has(ast)) return;
+    seen.add(ast);
+    if (
+      ast.annotations?.["parseOptions"] !== undefined ||
+      (ast.checks?.some(check => check.annotations?.["parseOptions"] !== undefined) ?? false)
+    ) {
+      throw new ChannelError({ code: "invalid_definition" });
+    }
+    ast.encoding?.forEach(link => {
+      visit(link.to);
+    });
+    Match.value(ast).pipe(
+      Match.tag("Unknown", "Any", "ObjectKeyword", () => {
+        throw new ChannelError({ code: "invalid_definition" });
+      }),
+      Match.tag("Declaration", declaration => {
+        if (!allowOpaque) throw new ChannelError({ code: "invalid_definition" });
+        declaration.typeParameters.forEach(visit);
+      }),
+      Match.tag("Objects", objects => {
+        objects.propertySignatures.forEach(property => visit(property.type));
+        objects.indexSignatures.forEach(index => {
+          // Filtered keys may disappear silently; a channel contract must retain them.
+          if (
+            index.parameter._tag !== "String" ||
+            index.parameter.checks !== undefined ||
+            index.parameter.encoding !== undefined
+          ) {
+            throw new ChannelError({ code: "invalid_definition" });
+          }
+          visit(index.parameter);
+          visit(index.type);
+        });
+      }),
+      Match.tag("Arrays", arrays => {
+        arrays.elements.forEach(visit);
+        arrays.rest.forEach(visit);
+      }),
+      Match.tag("Union", union => {
+        union.types.forEach(visit);
+      }),
+      Match.tag("Suspend", suspend => {
+        visit(suspend.thunk());
+      }),
+      Match.orElse(() => undefined),
+    );
+  };
+  visit(schema.ast);
+};
+const DefinitionSchema = Schema.Struct({
+  authMethods: Schema.Array(Schema.declare(AuthMethod.isAuthMethod)),
+  definitionSettings: SchemaDefinition,
+  deploymentSettings: SchemaDefinition,
+  exposure: Exposure,
+  extensions: Schema.optionalKey(
+    Schema.Record(Schema.String, SchemaDefinition).check(
+      Schema.makeFilter(values => Object.keys(values).every(Schema.is(ExtensionKey))),
+    ),
+  ),
+  features: Features,
+  protocol: Schema.optionalKey(Protocol),
+  requiredChecks: RequiredChecks,
+  state: SchemaDefinition,
+}).check(
+  Schema.makeFilter(({ features, protocol }) => {
+    if (protocol === undefined) {
+      return features.operations === undefined && features.readContext === undefined;
+    }
+    const operations = features.operations ?? [];
+    return (
+      operations.includes("present_outcome") &&
+      new Set(operations).size === operations.length &&
+      // A long text arrives as messages before its outcome.
+      (features.maxTextLength === undefined || operations.includes("create_message"))
+    );
+  }),
+);
+
+/** Validate declarations at registration as well as at builder time. */
+export const validateDefinition = (
+  definition: Definition,
+  providerId?: string,
+  methods?: readonly AuthMethod.Any[],
+): void => {
+  try {
+    Schema.decodeUnknownSync(DefinitionSchema)(definition, { onExcessProperty: "error" });
+    for (const schema of [
+      definition.definitionSettings,
+      definition.deploymentSettings,
+      definition.state,
+      ...Object.values(definition.extensions ?? {}),
+    ]) {
+      // A JSON projection must exist; it is catalog metadata, never the execution validator.
+      checkSchema(schema);
+      Schema.toJsonSchemaDocument(schema);
+    }
+    const seen = new Set<string>();
+    for (const method of definition.authMethods) {
+      if (seen.has(method.identifier) || (methods !== undefined && !methods.includes(method))) {
+        throw new ChannelError({ code: "invalid_definition" });
+      }
+      seen.add(method.identifier);
+      Schema.decodeUnknownSync(SchemaDefinition)(method.material);
+      Schema.decodeUnknownSync(SchemaDefinition)(method.value);
+      for (const schema of [
+        method.material,
+        method.value,
+        ...(method.setup === undefined ? [] : [method.setup]),
+      ]) {
+        checkSchema(schema, true);
+      }
+    }
+    if (
+      providerId !== undefined &&
+      Object.keys(definition.extensions ?? {}).some(key => !key.startsWith(`${providerId}/`))
+    ) {
+      throw new ChannelError({ code: "invalid_definition" });
+    }
+  } catch {
+    throw new ChannelError({ code: "invalid_definition" });
+  }
+};
+
+export interface ChannelOptions {
+  readonly name?: string;
+  readonly description?: string;
+}
+
+/** Create a Channel from its contract. */
+export const make = <const Id extends string, const O extends Definition & ChannelOptions>(
+  identifier: Id,
+  options: O,
+): AgentChannel<Id, O> => {
+  validateIdentifier("agent-channel", identifier);
+  const { description, name, ...definition }: Definition & ChannelOptions = options;
+  validateDefinition(definition);
+  return {
+    ...PipeableProto,
+    [TypeId]: TypeId,
+    definition: Object.freeze({
+      ...definition,
+      authMethods: Object.freeze([...definition.authMethods]),
+      features: Object.freeze({ ...definition.features }),
+      requiredChecks: Object.freeze([...definition.requiredChecks]),
+      ...(definition.extensions === undefined
+        ? {}
+        : { extensions: Object.freeze({ ...definition.extensions }) }),
+    }),
+    description,
+    identifier,
+    name,
+  } as AgentChannel<Id, O>;
+};
+export const isAgentChannel = (value: unknown): value is Any =>
+  Predicate.hasProperty(value, TypeId);
+
+export * as AgentChannel from "./AgentChannel.ts";