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

Permissions in 0.2.5

  • 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

transcript.test.ts16.9 KB
// Regression coverage for transcript using the real chat modules.
// Fixtures exercise the same behavior and assertions as the JavaScript tests.
import { item as fixtureItem } from "./ui-for-tests.test.ts";
import assert from "node:assert/strict";
import test from "node:test";
import { harness, tree, nodes, chat as makeChat, transcript as initial } from "./ui-for-tests.test.ts";
import { applyEvent, noteSession, sessionChanges } from "./transcript.ts";
import * as Effect from "effect/Effect";
import { HostCallFailed } from "convergence/effect";
import { InputLedger, withController } from "./testing.ts";
import { onChatChanged } from "./events.ts";
import {
  renderTool as toolView,
  renderReasoning as reasoningView,
  renderFold as foldView,
  renderUser,
  renderItems,
  keepLineBreaks,
} from "./views/rows.ts";
import type { Transcript, ToolItem, TextItem, UserItem } from "./state.ts";
import type { ToolGroup } from "./grouping.ts";
import type { Chat, TranscriptItem } from "convergence";
const h = harness(),
  renderers = h.renderers;
const renderTool = (t: Transcript, item: ToolItem, chat: Chat, folded?: boolean) =>
  tree(toolView(h.v, t, item, chat, folded));
const renderReasoning = (t: Transcript, item: TextItem, folded?: boolean) => tree(reasoningView(h.v, t, item, folded));
const renderFold = (chat: Chat, t: Transcript, entry: ToolGroup, last?: boolean) =>
  tree(foldView(h.v, chat, t, entry, last));
// A row and what it opens: the activity row, then the body when open.
const header = (node: import("./ui-for-tests.test.ts").TestNode) => node.children[0];
const body = (node: import("./ui-for-tests.test.ts").TestNode) => node.children[1];
const transcript = initial;
const start = (t: Transcript, id = "tool") =>
  applyEvent(t, {
    event: "tool_call_started",
    content: [],
    locations: [],
    id,
    name: "test",
    kind: "execute",
    title: "Run test",
    status: "running",
    input: {},
  });

test("tools default closed and preserve manual expansion across every status", () => {
  for (const status of ["running", "completed", "failed", "cancelled"] as const) {
    for (const manual of [false, true]) {
      const t = transcript();
      start(t);
      assert.equal(body(renderTool(t, t.items[0] as ToolItem, makeChat())), undefined);
      if (manual) header(renderTool(t, t.items[0] as ToolItem, makeChat())).onClick();
      start(t); // A repeated snapshot must not change the user's choice.
      applyEvent(t, { event: "tool_call_updated", id: "tool", status, outputDelta: "output" });
      assert.equal(t.expanded.has("tool"), manual);
      assert.equal(body(renderTool(t, t.items[0] as ToolItem, makeChat())) !== undefined, manual);
    }
  }
});

test("a group is open while it is last, closes once something follows it, and keeps the user's choice", () => {
  const t = transcript();
  start(t);
  const entry: ToolGroup = { kind: "tools", id: "group", items: t.items };
  assert.notEqual(body(renderFold(makeChat(), t, entry, true)), undefined);
  assert.equal(body(renderTool(t, t.items[0] as ToolItem, makeChat(), true)), undefined);
  start(t, "second");
  assert.notEqual(body(renderFold(makeChat(), t, entry, true)), undefined);
  // Text after the group ends it.
  assert.equal(body(renderFold(makeChat(), t, entry, false)), undefined);
  header(renderFold(makeChat(), t, entry, false)).onClick();
  assert.notEqual(body(renderFold(makeChat(), t, entry, false)), undefined);
  // A group the user closed while it was active stays closed.
  const other: ToolGroup = { kind: "tools", id: "other", items: t.items };
  header(renderFold(makeChat(), t, other, true)).onClick();
  assert.equal(body(renderFold(makeChat(), t, other, true)), undefined);
  assert.equal(t.expanded.size, 0);
});

test("a growing tool group keeps one tail-following scroll container", () => {
  const t = transcript();
  start(t);
  const entry: ToolGroup = { kind: "tools", id: "group", items: t.items };
  const first = body(renderFold(makeChat(), t, entry, true));
  assert.equal(first.id, "fold-scroll-group");
  assert.equal(first.followEnd, true);

  start(t, "second");
  entry.items = t.items;
  const second = body(renderFold(makeChat(), t, entry, true));
  assert.equal(second.id, first.id);
  assert.equal(second.followEnd, true);
});

test("grouped thoughts and tools share their horizontal and vertical insets", () => {
  const t = transcript();
  start(t);
  const thought = fixtureItem({ id: "thought", role: "reasoning", text: "Reviewing the output" });
  t.items.push(thought);
  const tool = renderTool(t, t.items[0] as ToolItem, makeChat(), true);
  for (const running of [true, false]) {
    t.running = running;
    const reasoning = renderReasoning(t, thought, true);
    assert.equal(reasoning.padding, tool.padding);
    assert.equal(reasoning.paddingY, tool.paddingY);
    assert.equal(header(reasoning).paddingX, header(tool).paddingX);
    assert.equal(header(reasoning).paddingY, header(tool).paddingY);
  }
  // Opened, a thought and a tool call sit at the same inset.
  t.expanded.add("tool");
  t.expanded.add("thought");
  const openTool = renderTool(t, t.items[0] as ToolItem, makeChat(), true);
  const openThought = renderReasoning(t, thought, true);
  assert.equal(body(openThought).paddingX, body(openTool).paddingX);
  assert.equal(body(openThought).paddingY, body(openTool).paddingY);
});

test("tool calls show their icon in a fold too; thoughts show none", () => {
  const t = transcript();
  start(t);
  const thought = fixtureItem({ id: "thought", role: "reasoning", text: "Reviewing the output" });
  t.items.push(thought);
  // The icons of a row's activity line, the chevron that opens it aside.
  const icons = (row: import("./ui-for-tests.test.ts").TestNode) =>
    nodes(header(row))
      .filter((n) => n.type === "icon" && !n.name.startsWith("chevron"))
      .map((n) => n.name);
  for (const folded of [true, false]) {
    assert.deepEqual(icons(renderTool(t, t.items[0] as ToolItem, makeChat(), folded)), ["square-terminal"]);
    assert.deepEqual(icons(renderReasoning(t, thought, folded)), []);
  }
});

test("a tool another plugin renders is left to that plugin", () => {
  const t = transcript();
  start(t);
  renderers.push({ plugin: "bash-cards", name: "test", kind: null });
  try {
    const row = renderTool(t, t.items[0] as ToolItem, makeChat());
    assert.deepEqual(row, { type: "tool_view", call: (t.items[0] as ToolItem).call, id: "tool" });
  } finally {
    renderers.length = 0;
  }
  assert.equal(renderTool(t, t.items[0] as ToolItem, makeChat()).type, "div", "without a renderer the chat draws it");
});

assert.equal(typeof applyEvent, "function", "the imported implementation is available");

// Cline sends a command's result only as structured output. The live
// reducer dropped it, and the open row showed the command's input instead.
test("a tool update's output reaches the row", () => {
  const t = transcript();
  start(t);
  applyEvent(t, { event: "tool_call_updated", id: "tool", status: "completed", output: "a.txt\nb.txt" });
  const item = t.items[0] as ToolItem;
  assert.equal(item.call.output, "a.txt\nb.txt");
  header(renderTool(t, item, makeChat())).onClick();
  const shown = JSON.stringify(body(renderTool(t, item, makeChat())));
  assert.ok(shown.includes("a.txt\\nb.txt"), "the text itself, not its JSON form");
  assert.ok(!shown.includes('\\"a.txt'), "not quoted");
});

// A prompt's single line breaks stay line breaks; Markdown alone would join
// them into spaces. Code fences keep their lines untouched.
test("a sent prompt keeps its line breaks", () => {
  assert.equal(keepLineBreaks("one\ntwo\n\nthree"), "one  \ntwo\n\nthree");
  assert.equal(keepLineBreaks("see:\n```\na\nb\n```\nend"), "see:  \n```\na\nb\n```\nend");
  const { v } = harness();
  const user: UserItem = { id: "u1", role: "user", blocks: [{ type: "text", text: "first\nsecond" }] };
  const shown = JSON.stringify(tree(renderUser(v, "c", { ...transcript([user]), running: false }, user)));
  assert.ok(shown.includes("first  \\nsecond"));
});

test("a message offers Edit only when its agent can rewind its own conversation", () => {
  const { v } = harness();
  const user: UserItem = { id: "u1", role: "user", blocks: [{ type: "text", text: "hello" }] };
  const t = { ...transcript([user]), running: false };
  v.controller.state.chats.c = makeChat({ agentId: "acp" });
  for (const [capabilities, shown] of [
    [{}, false],
    [{ rollback: false }, false],
    [{ rollback: true }, true],
  ] as const) {
    v.controller.state.agents.acp = { id: "acp", name: "ACP", capabilities } as never;
    const ids = nodes(tree(renderUser(v, "c", t, user))).map((node) => node.id);
    assert.equal(ids.includes("edit-u1"), shown, JSON.stringify(capabilities));
  }
});

// A divider sits above the first message sent to another agent (a handoff)
// or to a new native session of the same agent, and nowhere else.
const say = (id: string): UserItem => ({ id, role: "user", blocks: [{ type: "text", text: id }] });
const at = (agentId: string, sessionId: string | null) => ({ agentId, sessionId });
test("dividers mark handoffs and new sessions between user messages only", () => {
  const items = [
    say("u1"),
    { id: "r1", role: "assistant", text: "reply" },
    say("u2"),
    say("u3"),
    { id: "r3", role: "assistant", text: "reply" },
    say("u4"),
    say("u5"),
    say("u6"),
    say("u7"),
  ] as TranscriptItem[];
  const changes = sessionChanges(items, {
    u1: at("a", "s1"),
    u2: at("a", "s1"),
    u3: at("b", "sb"),
    u4: at("b", "sb2"),
    // Not known yet (a first send that creates its session): the same session.
    u5: at("b", null),
    u6: at("b", "sb2"),
    u7: at("a", "s1"),
  });
  assert.deepEqual(Object.fromEntries(changes), {
    u3: { kind: "handoff", from: "a", to: "b" },
    u4: { kind: "session", from: "b", to: "b" },
    u7: { kind: "handoff", from: "b", to: "a" },
  });
  // An older host reports no sessions: no dividers.
  assert.equal(sessionChanges(items, {}).size, 0);
});

test("the divider shows the old and new agent above the message, and a live message after a handoff gets one", () => {
  const t = initial([say("u1"), { id: "r1", role: "assistant", text: "reply" } as TranscriptItem]);
  t.running = false;
  t.sessions = { u1: at("a", "s1") };
  h.controller.state.agents.a = { id: "a", name: "A", icon: "<svg id='a'/>" } as never;
  h.controller.state.agents.b = { id: "b", name: "B", icon: "<svg id='b'/>" } as never;
  const handedOff = makeChat({ agentId: "b", sessionId: "sb" });
  const u2 = say("u2");
  t.items.push(u2);
  noteSession(t, u2, handedOff);
  const rows = renderItems(h.v, handedOff, t, t.items);
  const texts = (row: unknown) => nodes(row).flatMap((node) => (typeof node.text === "string" ? [node.text] : []));
  assert.equal(rows.length, 3);
  assert.ok(!texts(rows[0]).includes("Handed off"));
  const divider = nodes(rows[2]);
  assert.deepEqual(
    divider.filter((node) => node.type === "icon" && node.svg).map((node) => node.svg),
    ["<svg id='a'/>", "<svg id='b'/>"],
  );
  const shown = texts(rows[2]);
  assert.ok(shown.indexOf("Handed off") < shown.indexOf("u2"), "the divider is above the message");
  // The same agent in a new session.
  const u3 = say("u3");
  t.items.push(u3);
  noteSession(t, u3, makeChat({ agentId: "b", sessionId: "sb2" }));
  const again = renderItems(h.v, handedOff, t, t.items);
  assert.ok(texts(again[3]).includes("New session"));
  assert.equal(texts(again).filter((text) => text === "Handed off").length, 1);
});

/// A send that creates or recovers its session reports its message before
/// the session exists; the chat's change to the new session moves the
/// message there, so the "New session" divider shows live, not only after
/// a reload. A change of a chat that is not running moves nothing.
test("a send that recovers its session shows the New session divider live", async () => {
  await withController(new InputLedger(), (c) =>
    Effect.gen(function* () {
      const before = makeChat({ id: "c1", agentId: "a", sessionId: "s1", status: "running" });
      c.state.chats.c1 = before;
      const t = initial([say("u1"), { id: "r1", role: "assistant", text: "reply" } as TranscriptItem]);
      t.sessions = { u1: at("a", "s1") };
      c.state.transcripts.c1 = t;
      const u2 = say("u2");
      t.items.push(u2);
      noteSession(t, u2, before);
      assert.equal(sessionChanges(t.items, t.sessions).size, 0);
      yield* onChatChanged(c, { event: "chat_changed", chat: { ...before, sessionId: "s2" } });
      assert.deepEqual(Object.fromEntries(sessionChanges(t.items, t.sessions)), {
        u2: { kind: "session", from: "a", to: "a" },
      });
      yield* onChatChanged(c, { event: "chat_changed", chat: { ...before, sessionId: "s3", status: "idle" } });
      assert.deepEqual(t.sessions.u2, at("a", "s2"));
    }),
  );
});

/// A code mode program's calls come with the updates of its `execute`
/// call; opened, the row shows one row per call, its input and how it
/// ended, in a card above the program.
test("an execute row shows the calls its program made", () => {
  const t = transcript();
  applyEvent(t, {
    event: "tool_call_started",
    content: [],
    locations: [],
    id: "x",
    name: "execute",
    kind: "other",
    title: "Run plugin tools",
    status: "running",
    input: { code: "return await tools.weather.forecast({ city: 'Oslo' })" },
  });
  applyEvent(t, {
    event: "tool_call_updated",
    id: "x",
    calls: [
      { tool: "weather.forecast", status: "completed", input: { city: "Oslo" } },
      { tool: "my-db.search-rows", status: "failed" },
    ],
  });
  const item = t.items[0] as ToolItem;
  assert.equal(item.call.calls?.length, 2);
  const texts = (node: unknown) => nodes(node).flatMap((n) => (typeof n.text === "string" ? [n.text] : []));
  const closed = renderTool(t, item, makeChat());
  assert.ok(texts(closed).includes("2 calls"), "the row counts the calls");
  assert.ok(!texts(closed).includes("weather.forecast"), "a row opens only on click");
  t.expanded.add("x");
  const open = renderTool(t, item, makeChat());
  const shown = texts(open);
  assert.ok(shown.includes("weather.forecast") && shown.includes("city: Oslo") && shown.includes("my-db.search-rows"));
  assert.ok(nodes(open).some((n) => n.type === "icon" && n.name === "circle-alert"), "the failed call says so");
  assert.ok(nodes(open).some((n) => n.type === "code"), "the program follows the calls");
});

test("an error reported as a notice and as the turn's failure shows once", () => {
  const t = initial();
  const expired = "This API key has expired.";
  applyEvent(t, { event: "run_started" });
  applyEvent(t, { event: "notice", level: "error", message: expired });
  applyEvent(t, { event: "notice", level: "error", message: expired });
  applyEvent(t, { event: "run_finished", outcome: { status: "failed", message: expired } });
  assert.deepEqual(
    t.items.filter((item) => item.role === "notice").map((item) => item.role === "notice" && item.text),
    [expired],
  );
});

test("Send again shows the edited text and a busy chat until the host has it, and a failed edit puts the old text back", async () => {
  const { renderTranscript: transcriptOf } = await import("./views/rows.ts");
  let release: (fail: boolean) => void = () => {};
  const held = harness((method) =>
    method === "host/chats.edit_message"
      ? Effect.callback<unknown, HostCallFailed>((resume) => {
          release = (fail) =>
            resume(
              fail
                ? Effect.fail(new HostCallFailed({ method, code: -32000, message: "the agent cannot rewind" }))
                : Effect.succeed({}),
            );
        })
      : undefined,
  );
  const chat = makeChat({ id: "c", agentId: "codex", sessionId: "s" });
  held.controller.state.chats.c = chat;
  const t = held.controller.transcript("c");
  t.items = [say("old text"), { id: "r1", role: "assistant", text: "reply" } as TranscriptItem];
  t.loaded = true;
  const texts = () => nodes(tree(transcriptOf(held.v, chat))).flatMap((node) => (typeof node.text === "string" ? [node.text] : []));
  const markdown = () =>
    nodes(tree(transcriptOf(held.v, chat))).flatMap((node) => (node.type === "markdown" ? [String(node.text ?? "")] : []));

  for (const fail of [false, true]) {
    t.editing = "old text";
    t.editText = "new text";
    const sent = Effect.runPromise(held.controller.submitEdit("c", "old text").pipe(Effect.exit));
    await new Promise((resolve) => setTimeout(resolve, 0));
    const shown = [...texts(), ...markdown()].join("\n");
    assert.ok(shown.includes("new text") && !shown.includes("old text"), `the edited text shows at once: ${shown}`);
    assert.ok(texts().includes("Sending again…"), "the chat is busy");
    release(fail);
    await sent;
    assert.ok(!texts().includes("Sending again…"));
    if (fail) {
      const after = [...texts(), ...markdown()].join("\n");
      assert.ok(after.includes("old text"), `a failed edit shows the old text again: ${after}`);
    }
    // The host's reset replaces the items after a successful edit.
    t.items = [say("old text"), { id: "r1", role: "assistant", text: "reply" } as TranscriptItem];
  }
});

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.