Skip to content

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

10.2 KB
Raw Blame
import { isDeepEqual } from '../deep-equal';
import type { Attachment, Command, Snapshot } from './contract';
import { SessionReplica } from './replica';
import type { TranscriptNotice } from './replica';
import { commandStatusSchema, snapshotSchema } from './validation';

export type ClientCommand = Omit<Command, 'origin'>;
export type CommandStatus = Snapshot['commandStatuses'][number];
/** Transport methods must validate server JSON before returning typed receipts. */
export type AttachmentUpload = {
  attachmentId: string;
  name: string;
  mimeType: string;
  data: string;
};
export interface SessionTransport {
  uploadAttachment?(sessionId: string, file: AttachmentUpload): Promise<Attachment>;
  snapshot(sessionId: string, pageToken: string | null): Promise<unknown>;
  subscribe(
    sessionId: string,
    after: number,
    onEvent: (event: unknown) => void,
    onError: (error: Error) => void,
    onCursor: (sequence: number) => void
  ): () => void;
  submit(command: ClientCommand): Promise<CommandStatus>;
  reconcile?(command: ClientCommand): Promise<CommandStatus>;
  commandStatus(sessionId: string, commandId: string): Promise<CommandStatus>;
}
export type ChatView = {
  snapshot: Snapshot | null;
  connected: boolean;
  error: string | null;
  notices: TranscriptNotice[];
};

/** Client transport disconnects preserve execution state and command identity. */
export class SessionChatClient {
  private replica: SessionReplica | null = null;
  private view: ChatView = { snapshot: null, connected: false, error: null, notices: [] };
  private off: (() => void) | null = null;
  private generation = 0;
  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
  private pending: ClientCommand | null = null;
  private readonly listeners = new Set<() => void>();

  constructor(
    readonly sessionId: string,
    private readonly transport: SessionTransport
  ) {}
  getSnapshot = (): ChatView => this.view;
  subscribe = (listener: () => void): (() => void) => {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  };

  async connect(): Promise<void> {
    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
    this.reconnectTimer = null;
    const generation = ++this.generation;
    this.off?.();
    this.off = null;
    this.publish(false, null);
    try {
      const first = snapshotSchema.parse(await this.transport.snapshot(this.sessionId, null));
      if (first.session.sessionId !== this.sessionId)
        throw new Error('Snapshot belongs to another session.');
      const seen = new Set<string>();
      let next = first.nextPageToken;
      while (next !== null) {
        if (seen.has(next)) throw new Error('Snapshot pagination repeated a page token.');
        seen.add(next);
        const page = snapshotSchema.parse(await this.transport.snapshot(this.sessionId, next));
        if (
          page.throughSequence !== first.throughSequence ||
          page.session.sessionId !== first.session.sessionId ||
          page.session.epoch !== first.session.epoch
        )
          throw new Error('Snapshot pages changed version.');
        first.turns.push(...page.turns);
        first.items.push(...page.items);
        first.requests.push(...page.requests);
        first.commandStatuses.push(...page.commandStatuses);
        next = page.nextPageToken;
      }
      first.nextPageToken = null;
      if (generation !== this.generation) return;
      this.replica = new SessionReplica(first);
      this.publish(true, null);
      const off = this.transport.subscribe(
        this.sessionId,
        first.throughSequence,
        (event) => {
          if (generation !== this.generation) return;
          try {
            this.replica?.apply(event);
            this.publish(true, null);
          } catch (error) {
            this.disconnect(generation, String(error));
          }
        },
        (error) => {
          this.disconnect(generation, error.message);
        },
        (sequence) => {
          if (generation !== this.generation) return;
          try {
            this.replica?.advanceCursor(sequence);
            this.publish(true, null);
          } catch (error) {
            this.disconnect(generation, String(error));
          }
        }
      );
      if (generation === this.generation) this.off = off;
      else off();
    } catch (error) {
      if (generation === this.generation) {
        this.publish(false, String(error));
        this.scheduleReconnect();
      }
    }
  }

  async uploadAttachment(file: AttachmentUpload): Promise<Attachment> {
    if (!this.transport.uploadAttachment) throw new Error('Attachment upload is unavailable.');
    return this.transport.uploadAttachment(this.sessionId, file);
  }

  async send(
    text: string,
    commandId: string,
    attachments: Attachment[] = []
  ): Promise<CommandStatus> {
    const snapshot = this.replica?.snapshot();
    if (!snapshot || !this.view.connected || snapshot.session.connectivity !== 'online')
      throw new Error('HOST_OFFLINE: reconnect before sending.');
    if (snapshot.session.status !== 'ready' && snapshot.session.status !== 'running')
      throw new Error('Session is not ready for messages.');
    if (
      this.pending &&
      (this.pending.commandId !== commandId ||
        this.pending.body.type !== 'message.send' ||
        this.pending.body.text !== text ||
        !isDeepEqual(this.pending.body.attachments, attachments))
    )
      throw new Error('Resolve the previous message before sending another.');
    const command: ClientCommand = this.pending ?? {
      contractVersion: 1,
      commandId,
      sessionId: this.sessionId,
      epoch: snapshot.session.epoch,
      body: {
        type: 'message.send',
        text,
        attachments,
        delivery: 'queue',
      },
    };
    if (command.epoch !== snapshot.session.epoch)
      throw new Error('STALE_EPOCH: the previous message needs reconciliation.');
    if (new TextEncoder().encode(JSON.stringify(command)).byteLength > 59 * 1024)
      throw new Error(
        'Command exceeds the 59 KiB Console limit. Shorten the message or attach a file.'
      );
    this.pending = command;
    // Keep this command on uncertain transport failure; retry uses the same ID and body.
    const status = commandStatusSchema.parse(await this.transport.submit(command));
    return this.acceptReceipt(status, commandId);
  }

  async execute(body: Command['body'], commandId: string): Promise<CommandStatus> {
    const session = this.replica?.snapshot().session;
    if (!session || !this.view.connected || session.connectivity !== 'online')
      throw new Error('HOST_OFFLINE: reconnect before sending.');
    if (
      this.pending &&
      (this.pending.commandId !== commandId ||
        JSON.stringify(this.pending.body) !== JSON.stringify(body))
    )
      throw new Error('Resolve the previous command before sending another.');
    const command = this.pending ?? {
      contractVersion: 1 as const,
      commandId,
      sessionId: this.sessionId,
      epoch: session.epoch,
      body,
    };
    if (command.epoch !== session.epoch)
      throw new Error('STALE_EPOCH: reconcile the previous command.');
    if (new TextEncoder().encode(JSON.stringify(command)).byteLength > 59 * 1024)
      throw new Error(
        'Command exceeds the 59 KiB Console limit. Shorten the message or attach a file.'
      );
    this.pending = command;
    const status = commandStatusSchema.parse(await this.transport.submit(command));
    return this.acceptReceipt(status, commandId);
  }

  hasPendingCommand(): boolean {
    return this.pending !== null;
  }

  async reconcile(): Promise<CommandStatus> {
    if (!this.pending) throw new Error('No uncertain command.');
    const id = this.pending.commandId;
    const status = commandStatusSchema.parse(
      this.transport.reconcile
        ? await this.transport.reconcile(this.pending)
        : await this.transport.commandStatus(this.sessionId, id)
    );
    return this.acceptReceipt(status, id);
  }

  hasUnknownCommand(): boolean {
    return Boolean(
      this.pending &&
      this.view.snapshot?.commandStatuses.some(
        (status) => status.commandId === this.pending?.commandId && status.status === 'unknown'
      )
    );
  }

  async acknowledgeUnknown(): Promise<void> {
    if (!this.pending) throw new Error('No uncertain command.');
    const id = this.pending.commandId;
    const status = commandStatusSchema.parse(
      await this.transport.commandStatus(this.sessionId, id)
    );
    if (status.commandId !== id || status.status !== 'unknown')
      throw new Error('Check command status before acknowledging an unknown outcome.');
    this.replica?.recordReceipt(status);
    this.pending = null;
    this.publish(this.view.connected, null);
  }

  dispose(): void {
    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
    this.reconnectTimer = null;
    ++this.generation;
    this.off?.();
    this.off = null;
    this.publish(false, null);
  }

  private acceptReceipt(status: CommandStatus, commandId: string): CommandStatus {
    if (status.commandId !== commandId) throw new Error('Command receipt identity mismatch.');
    const current = this.replica?.recordReceipt(status) ?? status;
    if (current.status === 'unknown') {
      this.publish(this.view.connected, null);
      throw new Error('Command outcome is unknown. It will not be resent automatically.');
    }
    this.pending = null;
    this.publish(this.view.connected, null);
    if (current.status === 'rejected')
      throw new Error(current.message ?? current.code ?? 'Message rejected.');
    return current;
  }

  private disconnect(generation: number, error: string): void {
    if (generation !== this.generation) return;
    ++this.generation;
    this.off?.();
    this.off = null;
    this.publish(false, error);
    this.scheduleReconnect();
  }

  private scheduleReconnect(): void {
    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
    this.reconnectTimer = setTimeout(() => {
      this.reconnectTimer = null;
      void this.connect();
    }, 1000);
  }

  private publish(connected: boolean, error: string | null): void {
    this.view = {
      snapshot: this.replica?.snapshot() ?? null,
      connected,
      error,
      notices: [...(this.replica?.notices ?? [])],
    };
    for (const listener of this.listeners) listener();
  }
}