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 convergence/chat@0.2.3

Permissions in 0.2.3

  • 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.ts8.5 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,
  Plan,
  QuestionRequest,
  SecurityRequest,
  Skill,
  SlashCommand,
  TranscriptItem,
  Usage,
  UserSession,
  ViewHandle,
  Workspace,
} from "convergence";
import type { Cycle } from "./switcher.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("convergence").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 };
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;
  picker: { kind: "commands" | "skills" | "files"; query: string; index?: number } | null;
  files: readonly string[];
  queue: Prompt[];
  attachments: AttachedImage[];
  /// Structured, host-persisted attachments carried by a restored/transferred draft.
  carriedBlocks?: readonly import("convergence").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;
  /// Enter was pressed while the chat was not ready to send (the host was
  /// resuming its session, its options were loading): the prompt goes when
  /// it is, as a queued one (`true`) or sent (`false`).
  sendWhenReady?: boolean;
  regenerating?: boolean;
  /// 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("convergence").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;
  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>;
  expanded: Set<string>;
  folds: Map<string, boolean>;
  answers: Record<string, Record<string, unknown>>;
  editing: string | null;
  editText: string;
  /// The message an edit is sending again, until the host has it: the
  /// rewind before it can take seconds (Codex), and the chat shows the
  /// edited text and that it is busy meanwhile.
  resending?: string;
  loaded: boolean;
  loading?: Deferred.Deferred<void>;
  /// The host index of `items[0]`: the pages before it load on scroll up.
  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;
  drawn?: boolean;
  /// The pane shows its chat, not a skeleton waiting for its rows.
  ready?: boolean;
  stale?: boolean;
};
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, Pane> = {};
  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;
  paneViews: Record<string, { chatId: string; view: ViewHandle }> = {};
  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;
  promptedChat: string | null = null;
  // The chat the host was last asked to prepare; cleared when no chat is on screen, so showing it again prepares again.
  preparedChat: string | null = null;
  historyRead: Record<string, number> = {};
  historyChat: string | null = null;
  restored: Record<string, string> | null = null;
  saving = false;
  unsaved = false;
  draftTitles: Record<string, string> = {};
  ticking = false;
}
export function initialTranscript(): Transcript {
  return {
    items: [],
    approvals: [],
    questions: [],
    requests: [],
    plan: null,
    running: false,
    checkpoints: new Set(),
    sessions: {},
    expanded: new Set(),
    folds: new Map(),
    answers: {},
    editing: null,
    editText: "",
    loaded: false,
    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): Transcript {
  const fresh = initialTranscript();
  return {
    ...fresh,
    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,
    usage: kept.usage,
    checkpoints: kept.checkpoints instanceof Set ? kept.checkpoints : fresh.checkpoints,
    sessions: kept.sessions && typeof kept.sessions === "object" ? kept.sessions : fresh.sessions,
    expanded: kept.expanded instanceof Set ? kept.expanded : fresh.expanded,
    folds: kept.folds instanceof Map ? kept.folds : fresh.folds,
    carried: true,
  };
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=2 <4174.6 KB5 permissionsListed
0.2.4Oct 25, 2026>=2 <4174.2 KB5 permissionsListed
0.2.3Oct 24, 2026>=2 <4165.4 KB5 permissionsListed
0.2.2Oct 23, 2026>=2 <4165 KB5 permissionsListed
0.2.1Oct 6, 2026>=2 <3111.8 KB5 permissionsListed
0.2.0Oct 5, 2026>=2 <3105.1 KB5 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.