Fixes #756 (#763)

packages/types/src/channel/channel-adapter.ts

@@ -0,0 +1,43 @@
+import type {
+  ChannelAdapterHealthDto,
+  ChannelEgressDto,
+  ChannelIngressDto,
+} from './channel.dto.js';
+
+export type ChannelDeliveryErrorCode =
+  | 'invalid_route'
+  | 'destination_unavailable'
+  | 'delivery_failed';
+
+/** Terminal adapter delivery failure surfaced to the gateway/caller. */
+export class ChannelDeliveryError extends Error {
+  readonly name = 'ChannelDeliveryError';
+
+  constructor(
+    readonly code: ChannelDeliveryErrorCode,
+    message: string,
+    readonly retryable = false,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+/** Gateway policy boundary consumed by official channel adapters. */
+export interface ChannelIngressPort {
+  receive(ingress: ChannelIngressDto): Promise<void>;
+}
+
+/** Adapter egress boundary used by the gateway after agent output is ready. */
+export interface ChannelEgressPort {
+  send(egress: ChannelEgressDto): Promise<void>;
+}
+
+/** Shared lifecycle seam implemented by every official channel adapter. */
+export interface OfficialChannelAdapter {
+  readonly name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** Health is best-effort and never throws for ordinary disconnected state. */
+  health(): Promise<ChannelAdapterHealthDto>;
+}

packages/types/src/channel/channel.dto.ts

@@ -0,0 +1,97 @@
+/** JSON-safe metadata carried across channel adapter boundaries. */
+export type ChannelMetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly ChannelMetadataValue[]
+  | { readonly [key: string]: ChannelMetadataValue };
+
+export type ChannelSenderKind = 'user' | 'agent' | 'system';
+export type ChannelContentKind = 'text' | 'markdown' | 'code' | 'image' | 'file';
+export type ChannelAdapterStatus = 'connected' | 'degraded' | 'disconnected';
+export type ChannelAuthorizationRole = 'viewer' | 'operator' | 'admin';
+export type ChannelOperation = 'message.send' | 'approval.create' | 'session.stop';
+
+export interface ChannelAttachmentDto {
+  id: string;
+  name: string;
+  mimeType: string | null;
+  url: string;
+  sizeBytes?: number;
+}
+
+/** Canonical transport-neutral message shape for official channel adapters. */
+export interface ChannelMessageDto {
+  id: string;
+  channelName: string;
+  channelId: string;
+  senderId: string;
+  senderKind: ChannelSenderKind;
+  content: string;
+  contentKind: ChannelContentKind;
+  timestamp: string;
+  threadId?: string;
+  replyToId?: string;
+  attachments?: readonly ChannelAttachmentDto[];
+  metadata: Readonly<Record<string, ChannelMetadataValue>>;
+}
+
+/** Where an adapter must deliver a response for one normalized conversation turn. */
+/** Provisioned external identity after adapter allowlist/pairing checks pass. */
+export interface ChannelAuthorizedPrincipalDto {
+  channelUserId: string;
+  role: ChannelAuthorizationRole;
+  /** Needed when gateway policy must authorize a privileged Mosaic operation. */
+  mosaicUserId?: string;
+}
+
+/** Configuration-owned binding. Credentials are intentionally absent. */
+export interface ChannelBindingDto {
+  bindingId: string;
+  channelName: string;
+  workspaceId: string;
+  channelId: string;
+  logicalAgentId: string;
+  principals: Readonly<Record<string, ChannelAuthorizedPrincipalDto>>;
+}
+
+export interface ChannelResponseTargetDto {
+  channelId: string;
+  threadId?: string;
+}
+
+/**
+ * Stable channel-to-session route. Runtime provider, harness, model, process,
+ * and native runtime session identifiers are intentionally absent.
+ */
+export interface ChannelConversationRouteDto {
+  bindingId: string;
+  logicalAgentId: string;
+  conversationId: string;
+  channelName: string;
+  authorizationChannelId: string;
+  responseTarget: ChannelResponseTargetDto;
+}
+
+/** Authorized adapter-to-gateway ingress after native translation. */
+export interface ChannelIngressDto {
+  correlationId: string;
+  nativeMessageId: string;
+  operation: ChannelOperation;
+  principal: ChannelAuthorizedPrincipalDto;
+  message: ChannelMessageDto;
+  route: ChannelConversationRouteDto;
+}
+
+/** Gateway-to-adapter egress; runtime/provider identity remains gateway-internal. */
+export interface ChannelEgressDto {
+  correlationId: string;
+  message: ChannelMessageDto;
+  route: ChannelConversationRouteDto;
+}
+
+export interface ChannelAdapterHealthDto {
+  status: ChannelAdapterStatus;
+  detail?: string;
+}

packages/types/src/channel/index.ts

@@ -0,0 +1,2 @@
+export * from './channel-adapter.js';
+export * from './channel.dto.js';

packages/types/src/chat/events.ts

@@ -1,3 +1,4 @@
+import type { ChannelAttachmentDto } from '../channel/index.js';
 import type {
   CommandManifestPayload,
   SlashCommandApprovalResultPayload,
@@ -73,6 +74,7 @@ export interface ChatMessagePayload {
   provider?: string;
   modelId?: string;
   agentId?: string;
+  attachments?: readonly ChannelAttachmentDto[];
 }
 
 /** Routing decision summary included in session:info for transparency */

packages/types/src/index.ts

@@ -1,5 +1,6 @@
 export const VERSION = '0.0.0';
 
+export * from './channel/index.js';
 export * from './chat/index.js';
 export * from './agent/index.js';
 export * from './provider/index.js';