Official

chat

Built-in chat UI (JavaScript UI plugin).

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/chat@0.2.7

Permissions in 0.2.7

  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Send prompts, answer agent questions, and create, change, fork, revert, stop and group chats
  • Run other plugins' commands commands.runHighRuns commands of other plugins.Run the sidebar's New chat command from the title bar
  • Read chats chats.readMediumReads your transcripts and chat lists.Show workspaces, tasks, chats and transcripts, and follow them as agents work
  • Read files fs.readMediumReads files in the listed places.Suggest workspace files for @ mentionsPlaces: the open workspace
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw the chat grid, the title bar, and the Session panel with its rail buttonSlots: centertitlerailright

Files

state.ts13.4 KB
// Chat state belongs to the plugin scope; each pane reads only its chat's transcript.
// Drafts and queues retain their baseline storage and shared-state names.
import type * as Deferred from "effect/Deferred";
import type {
  AgentInfo,
  ApprovalRequest,
  AttachedImage,
  Chat,
  ComboMark,
  ConfigOption,
  Element,
  OpenInApp,
  Plan,
  QuestionRequest,
  SecurityRequest,
  Skill,
  SlashCommand,
  TranscriptItem,
  TurnSummary,
  Usage,
  UserSession,
  ViewHandle,
  Workspace,
} from "divergence";
import type { Cycle } from "./switcher.ts";
import { emptyLayouts } from "./layout.ts";
import type { Layouts } from "./layout.ts";
import { NO_SHORTCUTS, type Shortcuts } from "./shortcuts.ts";

export type UserItem = Extract<TranscriptItem, { role: "user" }>;
export type TextItem = Extract<TranscriptItem, { role: "assistant" | "reasoning" }>;
export type ToolItem = Extract<TranscriptItem, { role: "tool" }>;
export type Question = QuestionRequest & { submitting?: boolean };
export type Prompt = {
  text: string;
  attachments: readonly { id: string; name?: string }[];
  blocks?: readonly import("divergence").ContentBlock[];
  id?: string;
};
/// A draft waiting to start. Its prompt stays in its composer, editable,
/// until no chat runs; then the queue sends it.
export type QueuedChat = { chatId: string };
/// A prompt taken from the box before the chat could send it, and whether
/// it goes as a queued one.
export type Waiting = {
  queue: boolean;
  text: string;
  attachments: AttachedImage[];
  carriedBlocks: readonly import("divergence").ContentBlock[];
};
export type Composer = {
  text: string;
  /// The agent the options, commands and skills below are from.
  agentId: string | null;
  options: readonly ConfigOption[];
  commands: readonly SlashCommand[];
  skills: readonly Skill[];
  loading: boolean;
  /// The open picker and the word it completes: `start` is its `@`, `$`
  /// or `/`, `end` the caret (`segments.ts`, `triggerAt`). `commands` is a
  /// `/` that starts the text, `slash` one later in it.
  picker: {
    kind: "commands" | "slash" | "skills" | "files";
    query: string;
    start: number;
    end: number;
    index?: number;
  } | null;
  /// The word whose picker Escape closed, by where it starts: typing on in
  /// it leaves the picker closed.
  dismissed?: number;
  files: readonly string[];
  /// The query `files` answers, and why the last file search failed.
  filesFor?: string;
  filesError?: string;
  /// Where the caret was at the field's last change (UTF-16 units).
  caret?: number;
  /// The pills of `text` with the text they are for; for any other text
  /// they are found again (`picker.ts`, `segmentsOf`).
  segments?: { text: string; list: import("./segments.ts").Segment[] };
  /// The paths of the files tagged in this box: picked, or brought back with
  /// a draft, a queued prompt or a recalled message. They say where a file
  /// pill ends, so a path with a space stays one pill.
  tagged?: string[];
  /// Where the caret goes when this plugin's `text` replaces the field's.
  place?: { text: string; at: number };
  /// The earlier prompt Up or Down put in the box (`history.ts`): the arrows
  /// go on through the chat's prompts while `text` is still this one.
  recalled?: { id: string; text: string; files?: readonly string[] };
  queue: Prompt[];
  attachments: AttachedImage[];
  /// Structured, host-persisted attachments carried by a restored/transferred draft.
  carriedBlocks?: readonly import("divergence").ContentBlock[];
  /// Identity installed locally, distinct from a merely observed host draft.
  draftInputId?: string;
  editVersion?: number;
  submitting?: boolean;
  preparing?: boolean;
  /// The host is reconciling the chat with the agent's record: Send waits.
  syncing?: boolean;
  /// Why the last reconcile failed; sending still works.
  syncError?: string;
  /// Prompts Enter took from the box while the chat was not ready to send
  /// (the host was resuming its session, its options were loading): they
  /// wait over the box and go in order once it is.
  waiting?: Waiting[];
  regenerating?: boolean;
  /// How many messages were sent from here (not queued): each one takes
  /// the transcript to its end.
  sent?: number;
  /// Presentation only: never a durable transcript row or delivery receipt.
  outgoing?: {
    id: string;
    text: string;
    attachments: AttachedImage[];
    preview: boolean;
    intent?: "queue" | "steer";
    blocks?: UserItem["blocks"];
  };
  recovered?: {
    text: string;
    attachments: AttachedImage[];
    carriedBlocks?: readonly import("divergence").ContentBlock[];
    submission: { id: string; signature: string };
    /// Separately persisted typing recovered from a committed handoff race.
    durable?: boolean;
  }[];
  /// The input this composer is handing to the agent: it is already
  /// acknowledged, so it shows as the user's message, not as held input.
  dispatching?: string;
  error?: string;
  submission?: { id: string; signature: string };
  pendingEdit?: { id: string; revision: number; text: string };
};
export type Transcript = {
  items: TranscriptItem[];
  approvals: ApprovalRequest[];
  questions: Question[];
  requests: readonly SecurityRequest[];
  plan: Plan | null;
  running: boolean;
  /// When the run going now started, in ms since the epoch: the time of
  /// your message, or the moment the agent went on by itself.
  started?: number;
  /// How long each run this plugin saw end went, in ms, by the id of the
  /// item it ended on (`workedFor`, `stoppedAfter`).
  worked: Map<string, number>;
  checkpoints: Set<string>;
  /// The agent and native session each user message was sent in, by item id:
  /// a divider shows where either changed (`sessionChanges`).
  sessions: Record<string, UserSession>;
  /// The files each finished turn changed, by the id of the message that
  /// began it, with where its summary goes (`changes.ts`).
  turnFiles: Map<string, TurnSummary>;
  expanded: Set<string>;
  /// The prompts the kernel says five lines cut off (`clampedPrompt`), which
  /// are the only ones offered Read more.
  clamped: Set<string>;
  folds: Map<string, boolean>;
  answers: Record<string, Record<string, unknown>>;
  editing: string | null;
  editText: string;
  /// The message whose copy button shows a check, for two seconds after a copy.
  copied: string | null;
  /// The message an edit is sending again, until the host has it: the
  /// rewind before it can take seconds with some agents, and the chat shows
  /// the edited text and that it is busy meanwhile.
  resending?: string;
  /// The newest snapshot outcome is independent of a refresh in flight.
  snapshot: { kind: "unread" } | { kind: "ready" } | { kind: "failed"; error: string };
  loading?: Deferred.Deferred<void>;
  /// The host index of `items[0]`; older rows are fetched one page at a time
  /// when the scroller's viewport approaches this loaded beginning.
  start: number;
  /// An older page is being read.
  older?: boolean;
  version: number;
  usage?: Usage;
  finished?: Set<string>;
  /// Kept from before this plugin reloaded: its rows show at once, and its
  /// requests and history are read again the first time it shows.
  carried?: boolean;
};
/// `drawn`: the pane has rendered once, so the center can show it instead
/// of an empty view. `stale`: something changed while it was hidden, and it
/// renders when it shows again.
// A chat's pane and its composer, a view of its own the pane places, so
// typing renders the composer and not the transcript.
export type Pane = {
  chatId: string;
  view: ViewHandle;
  composer?: ViewHandle;
  centerPresentation?: ViewHandle;
  titlePresentation?: ViewHandle;
  centerPresented?: boolean;
  titlePresented?: boolean;
  drawn?: boolean;
  /// The pane shows its chat, not a skeleton waiting for its rows.
  ready?: boolean;
  stale?: boolean;
  /// It last drew the new chat page, and that page is leaving for the
  /// transcript (the first prompt went).
  landing?: boolean;
  departing?: boolean;
};
export type PreparingPane = {
  chatId: string;
  preparation: Deferred.Deferred<Pane>;
  view?: never;
  composer?: never;
  centerPresentation?: never;
  titlePresentation?: never;
  centerPresented?: never;
  titlePresented?: never;
  drawn?: never;
  ready?: never;
  stale?: never;
  landing?: never;
  departing?: never;
};
export type PaneEntry = Pane | PreparingPane;
export const registeredPane = (pane: PaneEntry | undefined): Pane | undefined => pane?.view ? pane : undefined;
export type ActivityProps = {
  icon?: string | Element;
  label?: string;
  detail?: string;
  extra?: Element | null;
  status?: Element | null;
  open?: boolean;
  onClick?: () => void;
  tone?: string;
  compact?: boolean;
};
/** A workspace picker's trigger: the workspace's name and mark, and whether it can change. The kernel's combobox opens the list. */
export type AnchorProps = { name: string; mark: ComboMark; can: boolean };
export class ChatState {
  chats: Record<string, Chat> = {};
  agents: Record<string, AgentInfo> = {};
  agentList: readonly AgentInfo[] = [];
  // The options each agent last answered with, by agent id: a composer
  // switched to that agent shows them while its own read is on its way,
  // never another agent's.
  agentOptions: Record<string, Composer["options"]> = {};
  composers: Record<string, Composer> = {};
  transcripts: Record<string, Transcript> = {};
  workspaces: Record<string, Workspace> = {};
  // Pane views by chat id, the most recently shown first in recentPanes.
  panes: Record<string, PaneEntry> = {};
  recentPanes: string[] = [];
  // The chat whose pane the center shows now.
  onScreen: string | null = null;
  // The chat the center switched to while its pane was not ready, and when.
  switching: { chatId: string; at: number } | null = null;
  // The chat whose composer is the main prompt box (`catchTyping`): typing
  // with nothing focused lands there. Only the selected chat's.
  mainPrompt: string | null = null;
  chatQueue: QueuedChat[] = [];
  // The queued draft just sent: it holds the queue until the host reports
  // it running, so a second chat cannot start in the gap.
  releasing: string | null = null;
  wsPicker: Record<string, boolean> = {};
  recent: string[] = [];
  itemImages: Record<string, string[] | "pending"> = {};
  switcher: Cycle | null = null;
  /// The chat whose title the title strip shows as a field (`/rename`),
  /// with what is typed in it.
  renaming: { chatId: string; text: string } | null = null;
  promptedChat: string | null = null;
  // The selected chat whose once-per-show preparation, history and retry effects have begun.
  shownChat: string | null = null;
  // Chats whose history is being read (`refreshHistory`).
  historyReading = new Set<string>();
  // Subagents whose transcript their tab is reading (`openSubagent`): `null`
  // while it reads, else why the read failed.
  taskReads = new Map<string, string | null>();
  restored: Record<string, string> | null = null;
  saving = false;
  unsaved = false;
  draftTitles: Record<string, string> = {};
  // Chats whose sent prompt starts a run the host has not reported yet:
  // the sidebar shows them running from the moment the prompt leaves.
  starting = new Set<string>();
  ticking = false;
  // The keys bound now, for the hints beside controls (`shortcuts.ts`).
  shortcuts: Shortcuts = NO_SHORTCUTS;
  // The tasks and the side split the host keeps, as their events left them.
  layouts: Layouts = emptyLayouts();
  // The apps on this machine a workspace opens in, and the one picked last
  // (`open-in.ts`); no apps on an older kernel.
  openIn: { apps: readonly OpenInApp[]; chosen: string | null } = { apps: [], chosen: null };
}
export function initialTranscript(): Transcript {
  return {
    items: [],
    approvals: [],
    questions: [],
    requests: [],
    plan: null,
    running: false,
    worked: new Map(),
    checkpoints: new Set(),
    sessions: {},
    turnFiles: new Map(),
    expanded: new Set(),
    clamped: new Set(),
    folds: new Map(),
    answers: {},
    editing: null,
    editText: "",
    copied: null,
    /// The newest snapshot outcome is independent of a refresh in flight.
  snapshot: { kind: "unread" },
    version: 0,
    start: 0,
  };
}
/// A transcript kept across a reload of this plugin (`keepTranscripts`): what
/// it showed, on a fresh one that is not loaded, so it is read again when it
/// shows. The code that kept it may have been another version: only the data
/// it shows is taken, each part only if it has the shape this code expects.
export function carriedTranscript(kept: Transcript) {
  const fresh = initialTranscript();
  return {
    items: Array.isArray(kept.items) ? kept.items : fresh.items,
    approvals: Array.isArray(kept.approvals) ? kept.approvals : fresh.approvals,
    questions: Array.isArray(kept.questions) ? kept.questions : fresh.questions,
    plan: kept.plan ?? null,
    running: kept.running === true,
    started: typeof kept.started === "number" ? kept.started : undefined,
    worked: kept.worked instanceof Map ? kept.worked : fresh.worked,
    usage: kept.usage,
    checkpoints: kept.checkpoints instanceof Set ? kept.checkpoints : fresh.checkpoints,
    sessions: kept.sessions && typeof kept.sessions === "object" ? kept.sessions : fresh.sessions,
    turnFiles: kept.turnFiles instanceof Map ? kept.turnFiles : fresh.turnFiles,
    expanded: kept.expanded instanceof Set ? kept.expanded : fresh.expanded,
    clamped: kept.clamped instanceof Set ? kept.clamped : fresh.clamped,
    folds: kept.folds instanceof Map ? kept.folds : fresh.folds,
  };
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.9latestNov 21, 2026>=5 <6349 KB5 permissionsListed
0.2.8Nov 16, 2026>=5 <6348.6 KB5 permissionsListed
0.2.7Nov 11, 2026>=5 <6314.3 KB5 permissionsListed
0.2.6Nov 9, 2026>=5 <6306.2 KB5 permissionsListed
0.2.5Oct 27, 2026>=2 <4178.6 KB5 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.