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.4

Permissions in 0.2.4

  • 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

composer-toolbar.test.ts19.6 KB
// The prompt toolbar: a draft queues the chat and has no prompt queue,
// typing while the agent works turns Stop into Send, and input already
// handed to the agent shows as the user's message, never as a queue card.
import assert from "node:assert/strict";
import test from "node:test";
import * as Effect from "effect/Effect";
import type { Chat, InputSnapshot, PendingInput } from "convergence";
import { HostCallFailed } from "convergence/effect";
import { renderComposer, renderLanding } from "./views/composer.ts";
import { renderPending } from "./views/pending.ts";
import { held } from "./testing.ts";
import { harness, chat, nodes, item, transcript } from "./ui-for-tests.test.ts";

// The catalogs a composer loads, empty.
const empty: Record<string, unknown> = {
  "host/chats.options": { options: [] },
  "host/chats.commands": { commands: [] },
  "host/chats.skills": { skills: [] },
};
const quiet = () => harness((method) => (method in empty ? Effect.succeed(empty[method]) : undefined));
const ids = (h: ReturnType<typeof quiet>, c: Chat) =>
  nodes(renderComposer(h.v, c))
    .map((node) => node.id)
    .filter((id): id is string => typeof id === "string");

test("the landing headline uses the display family without changing composer or workspace-chip text", () => {
  const h = quiet(),
    c = chat();
  h.controller.state.workspaces.w = { id: "w", name: "Starlight", path: "/starlight", position: 0 };
  const shown = nodes(renderLanding(h.v, c));
  const headline = shown.filter((node) => node.fontSize === "1.875rem");
  assert.deepEqual(
    headline.map((node) => node.text),
    ["What should we do in", "Starlight", "?"],
  );
  assert.ok(headline.every((node) => node.fontFamily === "Bricolage Grotesque" && !node.bold && node.weight === 500));
  assert.ok(shown.filter((node) => node.fontSize !== "1.875rem").every((node) => !node.fontFamily));
});

test("the landing workspace mark has equal gaps with and without a picker", () => {
  for (const picker of [false, true]) {
    const h = quiet(),
      c = chat();
    h.controller.state.workspaces.w = { id: "w", name: "Starlight", path: "/starlight", position: 0 };
    if (picker) h.controller.state.workspaces.other = { id: "other", name: "Orbit", path: "/orbit", position: 1 };
    const shown = nodes(renderLanding(h.v, c));
    const heading = shown.find((node) => node.children?.some((child) => child.text === "What should we do in"));
    const anchor = shown.find((node) =>
      node.children?.some((child) => child.text === "Starlight" && child.fontFamily === "Bricolage Grotesque"),
    );
    assert.ok(heading && anchor);
    assert.equal(heading.gap, 0, "do not add another gap before the picker padding");
    assert.equal(anchor.paddingX, 6);
    assert.equal(anchor.paddingLeft, 5, "compensate for the display face's side bearings");
    assert.equal(anchor.gap, 6, "match the space before the mark to the space after it");
  }
});

test("a draft queues the chat and has no prompt queue", () => {
  const h = quiet();
  const draft = chat({ id: "d" });
  h.controller.state.chats.d = draft;
  const shown = ids(h, draft);
  assert.ok(shown.includes("queue-chat-d"));
  assert.ok(!shown.includes("queue-d"));
});

test("a started chat queues prompts, not the chat", () => {
  const h = quiet();
  const started = chat({ id: "s", sessionId: "session" });
  h.controller.state.chats.s = started;
  const shown = ids(h, started);
  assert.ok(shown.includes("queue-s"));
  assert.ok(!shown.includes("queue-chat-s"));
});

test("a draft whose first prompt is starting the session is not a draft", () => {
  const h = quiet();
  const starting = chat({ id: "f", status: "running" });
  h.controller.state.chats.f = starting;
  assert.ok(!ids(h, starting).includes("queue-chat-f"));
});

test("typing and clearing refresh Stop/Send immediately without an agent event", async () => {
  const h = quiet();
  const running = chat({ id: "r", sessionId: "session", status: "running" });
  h.controller.state.chats.r = running;
  // A composer is typed in on screen; a hidden pane renders when it shows.
  Effect.runSync(h.controller.app.update({ route: "chat", chatId: "r" }));
  let shown = ids(h, running);
  h.controller.state.panes.r = {
    chatId: "r",
    view: {
      id: 1,
      update() {
        shown = ids(h, running);
      },
      remove() {},
    },
  };
  assert.ok(shown.includes("stop-r"));
  assert.ok(!shown.includes("send-r"));
  nodes(renderComposer(h.v, running))
    .find((node) => node.id === "prompt-r")
    ?.onChange({ value: "also check the tests" });
  await h.settle();
  assert.ok(shown.includes("send-r"));
  assert.ok(!shown.includes("stop-r"));
  nodes(renderComposer(h.v, running))
    .find((node) => node.id === "prompt-r")
    ?.onChange({ value: "   " });
  await h.settle();
  assert.ok(shown.includes("stop-r"));
  assert.ok(!shown.includes("send-r"));
  await h.close();
});

const snapshot = (inputs: PendingInput[]): InputSnapshot => ({
  chatId: "c1",
  agentId: "agent",
  sessionId: "session",
  generation: 1,
  revision: 1,
  inputs,
  running: true,
  settling: false,
  policyState: null,
  preparing: false,
});
const texts = (h: ReturnType<typeof quiet>, c: Chat) =>
  renderPending(h.v, c)
    .flatMap((card) => nodes(card))
    .map((node) => node.text);

test("a sent prompt the transcript already shows has no queue card while the agent picks it up", () => {
  const h = quiet();
  const c = chat({ id: "c1", status: "running" });
  h.controller.state.chats.c1 = c;
  h.controller.state.transcripts.c1 = transcript([item({ id: "sent", role: "user", text: "sent" })]);
  for (const state of ["dispatching", "native_admitted", "delivery_unknown"] as const) {
    h.controller.scheduler.snapshots.c1 = snapshot([held("sent", { intent: "send", originalIntent: "send", state })]);
    assert.deepEqual(renderPending(h.v, c), [], state);
  }
});

test("a sent prompt the agent refused keeps its card; its error is a toast, not card text", async () => {
  const h = quiet();
  const c = chat({ id: "c1", status: "running" });
  h.controller.state.chats.c1 = c;
  h.controller.state.transcripts.c1 = transcript([item({ id: "sent", role: "user", text: "sent" })]);
  h.controller.scheduler.receive(
    snapshot([held("sent", { intent: "send", originalIntent: "send", state: "rejected", error: "busy" })]),
  );
  const shown = texts(h, c);
  assert.ok(shown.includes("Send · not admitted"));
  assert.ok(!shown.includes("busy"));
  await h.settle();
  assert.deepEqual(h.notices, ["Pending input: busy"]);
  // The same error again is no second toast.
  h.controller.scheduler.receive(
    snapshot([held("sent", { intent: "send", originalIntent: "send", state: "rejected", error: "busy" })]),
  );
  await h.settle();
  assert.equal(h.notices.length, 1);
});

test("an input error saved before launch is no toast when the chat is first read; a new one is", async () => {
  const rejected = (id: string, error: string) =>
    held(id, { intent: "send", originalIntent: "send", state: "rejected", error });
  const saved = snapshot([rejected("old", "the folder is gone")]);
  const h = harness((method) =>
    method === "host/inputs.list" ? Effect.succeed(saved) : method in empty ? Effect.succeed(empty[method]) : undefined,
  );
  await Effect.runPromise(h.controller.scheduler.read("c1"));
  await h.settle();
  assert.deepEqual(h.notices, []);
  h.controller.scheduler.receive({
    ...snapshot([rejected("old", "the folder is gone"), rejected("new", "busy")]),
    revision: 2,
  });
  await h.settle();
  assert.deepEqual(h.notices, ["Pending input: busy"]);
});

test("dispatching alone never hides input; an outgoing preview replaces its card before pickup", () => {
  const h = quiet();
  const c = chat({ id: "c1" });
  h.controller.state.chats.c1 = c;
  h.controller.scheduler.snapshots.c1 = snapshot([
    held("sent", { intent: "send", originalIntent: "send" }),
    held("later"),
  ]);
  const composer = h.controller.composer("c1");
  composer.dispatching = "sent";
  assert.ok(texts(h, c).includes("sent"), "keep the card until a visible message takes ownership");
  composer.outgoing = { id: "sent", text: "sent", attachments: [], preview: true };
  const shown = texts(h, c);
  assert.ok(!shown.includes("sent"));
  assert.ok(shown.includes("later"), "a real queued follow-up still shows");
});

test("context status describes pending and ambiguous delivery, never completed delivery as in progress", () => {
  const h = quiet(),
    c = chat({ id: "c1", sessionId: "session" });
  h.controller.state.chats.c1 = c;
  for (const state of [
    "pending",
    "dispatching",
    "delivery_unknown",
    "native_admitted",
    "observed_consumed",
    "revoked",
  ] as const) {
    h.controller.scheduler.snapshots.c1 = {
      ...snapshot([]),
      running: false,
      context: { id: "ctx", attachmentId: "attachment", snapshotId: "snapshot", state },
    };
    const shown = nodes(renderComposer(h.v, c)).map((node) => node.text);
    assert.equal(shown.includes("History delivery in progress"), state === "dispatching", state);
    assert.equal(shown.includes("History prepared · delivered with your next Send"), state === "pending", state);
    assert.equal(
      shown.includes("History delivery is unknown · automatic replay is blocked"),
      state === "delivery_unknown",
      state,
    );
  }
});

test("new and existing chats never show a transcript regeneration control", () => {
  for (const sessionId of [undefined, "session"]) {
    for (const available of [false, true]) {
      const h = quiet(),
        c = chat({ id: "c1", sessionId });
      h.controller.state.chats.c1 = c;
      h.controller.composer(c.id).regenerating = true;
      h.controller.state.agents.agent = {
        id: "agent",
        name: "Agent",
        capabilities: { context: { labelled: true, ordinaryFiles: true, commands: false } },
      };
      h.controller.drafts.available = available;
      assert.ok(!ids(h, c).includes("regenerate-transcripts-c1"));
    }
  }
});

test("composer controls and meters share the prompt box's edges without a row-level horizontal inset", () => {
  for (const sessionId of [undefined, "session"]) {
    const h = quiet(),
      c = chat({ id: "c1", sessionId });
    h.controller.state.chats.c1 = c;
    const agent = { id: "agent", name: "Agent", capabilities: { usageLimits: true } };
    h.controller.state.agents.agent = agent;
    h.controller.state.agentList = [agent];
    h.controller.drafts.available = true;
    h.controller.state.transcripts.c1 = {
      ...transcript(),
      running: false,
      usage: { usedTokens: 17_000, contextWindow: 200_000 },
    };
    h.controller.composer(c.id).options = [
      {
        id: "approval",
        name: "Approval",
        category: "approval",
        kind: "select",
        value: "full",
        choices: [{ value: "full", name: "Full access" }],
      },
    ];
    const shown = nodes(renderComposer(h.v, c));
    // The prompt surface: the card fill, translucent over the transcript.
    const surface = (child: { background?: unknown }) => String(child.background).split("/")[0] === "card";
    // The surface shares a column with the queue list over it; the footer
    // follows that column.
    const stack = shown.find((node) => node.children?.some(surface));
    const parent = stack && shown.find((node) => node.children?.includes(stack));
    assert.ok(stack && parent, "the footer follows the prompt surface's column");
    const footer = parent.children[parent.children.indexOf(stack) + 1];
    assert.ok(footer);
    assert.equal(footer.padding ?? 0, 0);
    assert.equal(footer.paddingX ?? 0, 0);
    assert.equal(footer.paddingY, "small", "keep the existing vertical spacing");
    // The probe that measures the footer, the pills, then the meters.
    assert.equal(footer.children[0]?.id, "toolbar-c1");
    assert.deepEqual(
      footer.children.slice(2).map((child) => child.id),
      ["usage-c1", "context-c1"],
    );
    const left = nodes(footer.children[1]).map((node) => node.id);
    assert.ok(left.includes("agent-c1"));
    assert.ok(left.includes("opt-c1-approval"));
  }
});

test("a narrow footer keeps one line: the agent and approval pills show only their marks", () => {
  const h = quiet(),
    c = chat({ id: "c1" });
  h.controller.state.chats.c1 = c;
  const agent = { id: "agent", name: "Agent", icon: "<svg/>", capabilities: {} };
  h.controller.state.agents.agent = agent;
  h.controller.state.agentList = [agent];
  h.controller.drafts.available = true;
  h.controller.state.transcripts.c1 = { ...transcript(), running: false };
  h.controller.composer(c.id).options = [
    {
      id: "approval",
      name: "Approval",
      category: "approval",
      kind: "select",
      value: "full",
      choices: [{ value: "full", name: "Full access" }],
    },
  ];
  const pill = (id: string) => nodes(renderComposer(h.v, c)).find((node) => node.id === id);
  assert.equal(pill("agent-c1")?.type, "select", "labels while there is room");
  const probe = nodes(renderComposer(h.v, c)).find((node) => node.id === "toolbar-c1");
  const resize = probe?.onResize as ((size: { width: number; height: number }) => void) | undefined;
  assert.ok(resize);
  resize({ width: 420, height: 1 });
  const agentPill = pill("agent-c1");
  assert.equal(agentPill?.type, "combobox");
  assert.equal(agentPill?.label, "");
  assert.deepEqual(agentPill?.marks, [{ svg: "<svg/>" }]);
  const approval = pill("opt-c1-approval");
  assert.equal(approval?.label, "");
  assert.deepEqual(approval?.marks, [{ icon: "shield-off" }]);
  assert.match(String(approval?.tooltip), /Full access/);
  const footer = nodes(renderComposer(h.v, c)).find((node) => node.children?.[0]?.id === "toolbar-c1");
  assert.notEqual(footer?.children[1]?.flexWrap, "wrap", "never wraps onto more lines");
  resize({ width: 900, height: 1 });
  assert.equal(pill("agent-c1")?.type, "select");
});

test("manual regeneration uses only chat-scoped export APIs, preserves drafts, and surfaces failures", async () => {
  for (const failed of [false, true]) {
    const calls: { method: string; params: unknown }[] = [];
    const h = harness((method, params) => {
      if (!method.startsWith("host/artifacts.")) return undefined;
      calls.push({ method, params });
      if (method === "host/artifacts.list") return Effect.succeed({ artifacts: [{ id: "old" }, { id: "new" }] });
      return failed && (params as { artifactId: string }).artifactId === "old"
        ? Effect.fail(new HostCallFailed({ method, code: -32000, message: "Renderer unavailable" }))
        : Effect.succeed({});
    });
    const composer = h.controller.composer("c1");
    composer.text = "Unsent user input";
    composer.carriedBlocks = [{ type: "image", data: "unchanged", mimeType: "image/png" }];
    await Effect.runPromise(h.controller.regenerateTranscripts("c1"));
    assert.deepEqual(calls, [
      { method: "host/artifacts.list", params: { chatId: "c1" } },
      { method: "host/artifacts.regenerate", params: { chatId: "c1", artifactId: "old" } },
      { method: "host/artifacts.regenerate", params: { chatId: "c1", artifactId: "new" } },
    ]);
    assert.equal(composer.text, "Unsent user input");
    assert.deepEqual(composer.carriedBlocks, [{ type: "image", data: "unchanged", mimeType: "image/png" }]);
    assert.equal(composer.regenerating, false);
    assert.ok(h.notices.some((notice) => notice.includes(failed ? "Renderer unavailable" : "Regenerated 2")));
    assert.ok(h.notices.some((notice) => notice.includes(failed ? "1 of 2" : "2 of 2")));
    await h.close();
  }
});

// A host-prepared chat: the host reports `preparing` in the input snapshot.
const preparingSnapshot = (fields: Partial<InputSnapshot>): InputSnapshot =>
  ({ ...snapshot([]), chatId: "p", running: false, settling: false, preparing: false, ...fields }) as InputSnapshot;

test("Send is a spinner that cannot be pressed while the host prepares the chat, and typing stays enabled", async () => {
  const h = quiet();
  const prepared = chat({ id: "p", sessionId: "session" });
  h.controller.state.chats.p = prepared;
  h.controller.scheduler.snapshots.p = preparingSnapshot({ preparing: true });
  const shown = nodes(renderComposer(h.v, prepared));
  assert.ok(shown.some((node) => node.id === "send-preparing-p"));
  assert.ok(!shown.some((node) => node.id === "send-p"));
  assert.notEqual(shown.find((node) => node.id === "prompt-p")?.disabled, true);
  assert.equal(shown.find((node) => node.id === "queue-p")?.disabled, true);
  h.controller.scheduler.snapshots.p = preparingSnapshot({});
  const ready = nodes(renderComposer(h.v, prepared));
  assert.ok(ready.some((node) => node.id === "send-p"));
  assert.ok(!ready.some((node) => node.id === "send-preparing-p"));
  await h.close();
});

test("Enter while the host prepares the chat sends once it is ready, and says so meanwhile", async () => {
  const h = quiet();
  const prepared = chat({ id: "p", sessionId: "session" });
  h.controller.state.chats.p = prepared;
  h.controller.scheduler.snapshots.p = preparingSnapshot({ preparing: true });
  const composer = h.controller.composer("p");
  composer.text = "hello";
  composer.loading = false;
  await Effect.runPromise(h.controller.onSubmit("p", { value: "hello", secondary: false, shift: false }));
  await h.settle();
  const sent = () =>
    h.calls.filter((call) => call.method.startsWith("host/inputs.") && call.method !== "host/inputs.list");
  assert.deepEqual(sent(), [], "nothing goes while the host prepares");
  assert.equal(composer.text, "hello");
  const waiting = nodes(renderComposer(h.v, prepared));
  assert.ok(
    waiting.some((node) => node.text === "Sends when ready" || String(node.children?.[0] ?? "") === "Sends when ready"),
  );
  // A second Enter does not send it twice.
  await Effect.runPromise(h.controller.onSubmit("p", { value: "hello", secondary: false, shift: false }));
  h.controller.scheduler.snapshots.p = preparingSnapshot({});
  composer.loading = false;
  await new Promise((resolve) => setTimeout(resolve, 300));
  await h.settle();
  assert.equal(composer.sendWhenReady, undefined);
  assert.equal(composer.text, "", "the prompt went");
  assert.equal(composer.submission?.signature.includes("hello"), true, "the prompt was submitted once it was ready");
  await h.close();
});

test("a preparation error is a toast, not composer text, with Send available", async () => {
  const h = quiet();
  const prepared = chat({ id: "p", sessionId: "session" });
  h.controller.state.chats.p = prepared;
  h.controller.scheduler.receive(preparingSnapshot({ prepareError: "session expired" }));
  h.controller.composer("p").text = "hello";
  renderComposer(h.v, prepared);
  await h.settle();
  // The options read of a fake host never ends the composer's loading.
  h.controller.composer("p").loading = false;
  const shown = nodes(renderComposer(h.v, prepared));
  assert.ok(!shown.some((node) => String(node.children?.[0] ?? node.text ?? "").includes("session expired")));
  assert.ok(h.notices.includes("Preparing the conversation failed: session expired"));
  assert.notEqual(shown.find((node) => node.id === "send-p")?.disabled, true);
  await h.close();
});

test("the pickers keep showing the last options while new ones load, with no spinner", () => {
  const h = quiet(),
    c = chat();
  h.controller.state.chats.c = c;
  h.controller.state.transcripts.c = { ...transcript(), running: false };
  const composer = h.controller.composer(c.id);
  composer.agentId = c.agentId;
  composer.options = [
    {
      id: "approval",
      name: "Approval",
      category: "approval",
      kind: "select",
      value: "full",
      choices: [{ value: "full", name: "Full access" }],
    },
  ];
  composer.loading = true;
  const shown = nodes(renderComposer(h.v, c));
  assert.ok(!shown.some((node) => node.type === "spinner"));
  assert.equal(shown.find((node) => node.id === "opt-c-approval")?.value, "full");
});

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.