Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

6.2 KB
Raw Blame
/** Session interaction wire contract, version 1. */
export type Id = string;
/**
 * Where something was done: Switch's own two surfaces, or a messaging platform
 * by its key (`slack`, `teams`, `google_chat`, …). Any platform key is accepted
 * rather than a fixed list, so a newly registered platform needs no contract
 * change. The validator holds a key to the same pattern switch-core does.
 */
export type Surface = 'console' | 'switch-web' | (string & {});
export type Provider = string;
export type Origin = {
  surface: Surface;
  actorId: Id;
  roomId: Id | null;
  threadId: Id | null;
  messageId: Id | null;
};
export type Capability = {
  input: 'queue' | 'steer';
  approvals: boolean;
  questions: boolean;
  interrupt: boolean;
  reset: boolean;
  compact: boolean;
  modelChange: boolean;
  attachmentMimeTypes: string[];
  /** The host runs `message.retry`; absent from a host built before it, which means no. */
  retry?: boolean;
};
export type Attachment = {
  attachmentId: Id;
  name: string;
  mimeType: string;
  bytes: number;
  sha256?: string | null;
};
export type Item = {
  itemId: Id;
  turnId: Id;
  revision: number;
  kind: 'user-message' | 'assistant-message' | 'tool-activity';
  status: 'in-progress' | 'completed' | 'failed' | 'declined';
  title: string;
  text: string;
  attachments: Attachment[];
  origin: Origin | null;
};
export type ApprovalOption = {
  optionId: Id;
  label: string;
  decision: 'accept' | 'acceptForSession' | 'decline' | 'cancel';
};
export type Question = {
  questionId: Id;
  title: string;
  prompt: string;
  options: { optionId: Id; label: string; description: string | null }[];
  multiSelect: boolean;
  allowCustomAnswer: boolean;
};
export type Answer = { questionId: Id; selectedOptionIds: Id[]; customText: string | null };
export type RequestContent =
  | { kind: 'approval'; title: string; detail: string | null; options: ApprovalOption[] }
  | { kind: 'questions'; title: string; questions: Question[] };
export type Request = {
  requestId: Id;
  turnId: Id;
  revision: number;
  state: 'open' | 'submitting' | 'resolved' | 'closed';
  content: RequestContent;
  expiresAt: string | null;
};
export type SessionModel = { id: string; options: Record<string, string> };
/** How full the provider's context window was when last measured; `windowTokens` null when the provider does not say. */
export type SessionContext = { usedTokens: number; windowTokens: number | null; updatedAt: string };
export type ModelChoice = {
  id: string;
  label: string;
  options: Record<string, string[]>;
  imageInput?: boolean | null;
};
export type Session = {
  roomIds?: Id[];
  retired?: boolean;
  sessionId: Id;
  agentId: Id;
  provider: Provider;
  hostId: Id;
  epoch: Id;
  status: 'starting' | 'ready' | 'running' | 'stopped' | 'error';
  connectivity: 'online' | 'offline';
  capabilities: Capability;
  pendingRequestIds: Id[];
  models?: ModelChoice[];
  model?: SessionModel | null;
  context?: SessionContext | null;
};
export type HostBody =
  | { type: 'session.upsert'; session: Session }
  | {
      type: 'turn.upsert';
      turnId: Id;
      status: 'queued' | 'running' | 'completed' | 'interrupted' | 'error';
      commandId: Id | null;
    }
  | { type: 'item.upsert'; item: Item }
  | { type: 'request.opened'; request: Request }
  | {
      type: 'request.settled';
      requestId: Id;
      revision: number;
      outcome: 'answered' | 'cancelled' | 'expired' | 'interrupted' | 'provider-error';
      commandId: Id | null;
      result: { kind: 'approval'; optionId: Id } | { kind: 'questions'; answers: Answer[] } | null;
    }
  | {
      type: 'command.result';
      commandId: Id;
      status: 'applied' | 'rejected' | 'unknown';
      code: string | null;
      message: string | null;
    }
  | { type: 'notice'; level: 'info' | 'warning' | 'error'; code: string; message: string };
export type HostEvent = {
  contractVersion: 1;
  eventId: Id;
  sessionId: Id;
  epoch: Id;
  hostSequence: number;
  occurredAt: string;
  body: HostBody;
};
export type CommandBody =
  | {
      type: 'message.send';
      text: string;
      attachments: Attachment[];
      delivery: 'queue' | 'steer';
    }
  | {
      type: 'request.answer';
      requestId: Id;
      expectedRevision: number;
      answer: { kind: 'approval'; optionId: Id } | { kind: 'questions'; answers: Answer[] };
    }
  | { type: 'turn.interrupt'; turnId: Id }
  | { type: 'session.stop' }
  | { type: 'session.reset' }
  | { type: 'session.compact' }
  /** Run again the turn a room message started, which ended without an answer; nothing is posted again. */
  | { type: 'message.retry'; messageId: Id }
  | { type: 'session.model.set'; modelId: string; options: Record<string, string> };
/** The server sets origin from a verified identity. Do not trust origin from a client. */
export type Command = {
  contractVersion: 1;
  commandId: Id;
  sessionId: Id;
  epoch: Id;
  origin: Origin;
  body: CommandBody;
};
export type ServerBody =
  | HostBody
  | {
      type: 'command.status';
      commandId: Id;
      status: 'accepted' | 'dispatched' | 'applied' | 'rejected' | 'unknown';
      code: string | null;
      message: string | null;
    }
  | {
      type: 'request.submitting';
      requestId: Id;
      revision: number;
      commandId: Id;
      actorId: Id;
      surface: Surface;
    }
  | { type: 'session.connectivity'; connectivity: 'online' | 'offline' };
export type ServerEvent = {
  contractVersion: 1;
  eventId: Id;
  sessionId: Id;
  sequence: number;
  occurredAt: string;
  body: ServerBody;
};
export type Snapshot = {
  contractVersion: 1;
  throughSequence: number;
  session: Session;
  turns: Extract<HostBody, { type: 'turn.upsert' }>[];
  items: Item[];
  requests: (Request & {
    result: Extract<HostBody, { type: 'request.settled' }> | null;
    decidedBy: { actorId: Id; surface: Surface; commandId: Id } | null;
  })[];
  commandStatuses: Extract<ServerBody, { type: 'command.status' }>[];
  /** Recent notices (the newest ones only), each placed after the item it followed. */
  notices: SnapshotNotice[];
  nextPageToken: string | null;
};

export type SnapshotNotice = {
  level: 'info' | 'warning' | 'error';
  code: string;
  message: string;
  afterItemId: Id | null;
};