Official

sidebar

Built-in sidebar 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/sidebar@0.2.7

Permissions in 0.2.7

  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Add and remove workspaces, and create, rename, check off and archive chats
  • Run other plugins' commands commands.runHighRuns commands of other plugins.Open the chat search from the search button, and close the tab on screen with Cmd+W when its chat is part of a task
  • Read chats chats.readMediumReads your transcripts and chat lists.List workspaces and chats, and follow them as agents work
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw the sidebar, and its top controls in the title strip after the sidebar toggleSlots: lefttitle

Files

rows.test.ts14.9 KB
// What a row does when it is renamed, checked off, given a menu or a
// preview, against the fake host in testing.ts.
import assert from "node:assert/strict";
import { afterEach, mock, test } from "node:test";
import activate from "./main.ts";
import { fakeHost } from "./testing.ts";

afterEach(() => mock.timers.reset());

const day = (n: number) => `2026-10-0${n}T00:00:00.000Z`;
const type = (fake: ReturnType<typeof fakeHost>, id: string, value: string) =>
  (fake.node(id)?.onChange as (event: { value: string }) => void)({ value });

test("rename takes the keyboard, Escape keeps the title, and Enter on an untouched field writes nothing", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(1) }]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.action("row-c1", "Rename");
    await fake.settle();
    assert.deepEqual(fake.focused.slice(-1), ["rename-c1"], "the field has the keyboard");
    type(fake, "rename-c1", "Changed");
    (fake.node("rename-c1")?.onKey as (event: { key: string }) => void)({ key: "escape" });
    await fake.settle();
    assert.equal(fake.node("rename-c1"), undefined, "Escape closes the field");
    fake.action("row-c1", "Rename");
    await fake.settle();
    fake.click("rename-c1", "onSubmit");
    await fake.settle();
    assert.deepEqual(
      fake.calls.filter((call) => call.method === "host/chats.update"),
      [],
      "neither Escape nor an untouched Enter writes the title",
    );
  } finally {
    await dispose();
  }
});

test("leaving the rename field saves what was typed, and a field that leaves after Escape or after another row opened saves nothing", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(2) },
    { id: "c2", title: "Second", at: day(1) },
  ]);
  const dispose = activate(fake.api);
  const blur = (id: string) => (fake.node(id)?.onBlur as (event: { value: string }) => void)({ value: "" });
  const writes = () => fake.calls.filter((call) => call.method === "host/chats.update");
  try {
    await fake.settle();
    fake.action("row-c1", "Rename");
    await fake.settle();
    type(fake, "rename-c1", "Renamed");
    blur("rename-c1");
    await fake.settle();
    assert.deepEqual(writes(), [{ method: "host/chats.update", params: { chatId: "c1", title: "Renamed" } }]);
    assert.equal(fake.node("rename-c1"), undefined, "leaving the field closes it");

    fake.action("row-c2", "Rename");
    await fake.settle();
    const leaving = fake.node("rename-c2")?.onBlur as (event: { value: string }) => void;
    type(fake, "rename-c2", "Kept out");
    (fake.node("rename-c2")?.onKey as (event: { key: string }) => void)({ key: "escape" });
    await fake.settle();
    leaving({ value: "Kept out" });
    await fake.settle();
    assert.equal(writes().length, 1, "a blur after Escape writes nothing");

    fake.action("row-c2", "Rename");
    await fake.settle();
    const first = fake.node("rename-c2")?.onBlur as (event: { value: string }) => void;
    fake.action("row-c1", "Rename");
    await fake.settle();
    first({ value: "Second" });
    await fake.settle();
    assert.ok(fake.node("rename-c1"), "the old field's late blur leaves the new field open");
  } finally {
    await dispose();
  }
});

test("another row's pencil saves what was typed in the open field", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(2) },
    { id: "c2", title: "Second", at: day(1) },
  ]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.action("row-c1", "Rename");
    await fake.settle();
    type(fake, "rename-c1", "Renamed");
    fake.action("row-c2", "Rename");
    await fake.settle();
    assert.deepEqual(fake.calls.filter((call) => call.method === "host/chats.update"), [
      { method: "host/chats.update", params: { chatId: "c1", title: "Renamed" } },
    ]);
    assert.ok(fake.node("rename-c2"), "the field moved to the other row");
  } finally {
    await dispose();
  }
});

test("archiving the chat on screen from its row moves the screen to the next open chat", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(3) },
    { id: "c2", title: "Second", at: day(2) },
    { id: "c3", title: "Third", at: day(1) },
  ]);
  const dispose = activate(fake.api);
  try {
    fake.update({ chatId: "c2" });
    await fake.settle();
    fake.action("row-c2", "Archive");
    await fake.settle();
    assert.equal(fake.api.app.state().chatId, "c3");
    fake.action("row-c1", "Archive");
    await fake.settle();
    assert.equal(fake.api.app.state().chatId, "c3", "archiving a chat that is not on screen leaves the screen");
  } finally {
    await dispose();
  }
});

test("a check-off the host refuses puts the row back where it was", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(2) },
    { id: "c2", title: "Second", at: day(1) },
  ]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.fail("host/chats.update", "the store is read-only");
    fake.click("glyph-c2");
    await fake.settle();
    assert.deepEqual(fake.list(), ["heading-open", "row-c1", "row-c2"]);
    assert.deepEqual(fake.notices, ["Could not update the chat: the store is read-only"]);
  } finally {
    await dispose();
  }
});

test("a new chat the host refuses says so", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(1) }]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.fail("host/chats.create", "the workspace is gone");
    await fake.run("sidebar.newChat");
    await fake.settle();
    assert.deepEqual(fake.notices, ["Could not create a chat: the workspace is gone"]);
  } finally {
    await dispose();
  }
});

test("a task row's popover comes back after its menu was opened", async () => {
  const fake = fakeHost(
    [
      { id: "c1", title: "First", at: day(2) },
      { id: "c2", title: "Second", at: day(1) },
    ],
    [{ id: "t", chats: ["c1", "c2"], title: "Both" }],
  );
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.click("row-c1", "onSecondaryClick");
    await fake.settle();
    assert.ok(fake.node("row-menu"), "the menu opened");
    // Escape or a click away closes the kernel's list without telling the plugin.
    fake.click("row-c1", "onPointerLeave");
    fake.click("row-c1", "onPointerEnter");
    mock.timers.tick(1000);
    await fake.settle();
    assert.equal(fake.node("task-popover-t")?.open, true);
  } finally {
    await dispose();
  }
});

test("the row menu shows the keys its commands are bound to now", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(1) }]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.click("row-c1", "onSecondaryClick");
    await fake.settle();
    const options = fake.node("row-menu")?.options as { value: string; detail?: string }[];
    assert.deepEqual(
      options.map((option) => [option.value, option.detail]),
      [
        ["row-menu-pin", undefined],
        ["row-menu-snooze", undefined],
        ["row-menu-rename", undefined],
        ["row-menu-done", "⇧⌘M"],
        ["row-menu-archive", undefined],
      ],
    );
  } finally {
    await dispose();
  }
});

test("a right-click opens the row's menu where the pointer was, and Snooze moves the row to Snoozed until its time", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(2) },
    { id: "c2", title: "Second", at: day(1) },
  ]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    (fake.node("row-c1")!.onSecondaryClick as (e: unknown) => void)({ button: 2, x: 120, y: 14, modifiers: {} });
    await fake.settle();
    // The list hangs from a point in the row's menu slot, laid over the row from its top left corner.
    type Node = { type?: string; name?: string; left?: number; top?: number; id?: string; height?: number; children?: Node[] };
    const slot = (fake.node("row-c1")!.children as Node[]).find((child) => child.type === "slot" && child.name === "menu");
    const place = slot?.children?.[0];
    assert.deepEqual([place?.left, place?.top], [120, 14]);
    const menu = place?.children?.[0] as Node & { options: { value: string; icon?: string; submenu?: { options: { value: string }[] } }[]; onChange: (e: unknown) => void };
    assert.equal(menu.id, "row-menu");
    assert.equal(menu.children?.[0]?.height, 0, "a trigger with no height, so the list opens right on the point");
    assert.ok(menu.options.every((option) => option.icon), "every entry has its icon");
    const snooze = menu.options.find((option) => option.value === "row-menu-snooze")!;
    assert.deepEqual(snooze.submenu?.options.map((option) => option.value), ["hour", "hours", "day", "week", "always"]);
    const before = Date.now();
    menu.onChange({ value: "hour", option: "row-menu-snooze" });
    await fake.settle();
    assert.deepEqual(fake.list(), ["heading-open", "row-c2", "heading-snoozed"], "Snoozed starts folded, its heading at the foot");
    const saved = (fake.storage.get("placedChats") as Record<string, { section: string; until?: number }>)["c1"]!;
    assert.equal(saved.section, "snoozed");
    assert.ok(saved.until! >= before + 3_600_000 && saved.until! <= Date.now() + 3_600_000, "it wakes in an hour");
  } finally {
    await dispose();
  }
});

test("another plugin snoozes and unsnoozes a row through the divergence/sidebar service, by its task id", async () => {
  const fake = fakeHost(
    [
      { id: "c1", title: "First", at: day(3) },
      { id: "c2", title: "Second", at: day(2) },
      { id: "c3", title: "Third", at: day(1) },
    ],
    [{ id: "t1", chats: ["c2", "c3"] }],
  );
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    await fake.callService("divergence/sidebar", "snooze", { taskId: "c1", until: null });
    await fake.callService("divergence/sidebar", "snooze", { taskId: "t1", until: null });
    await fake.settle();
    const placed = fake.storage.get("placedChats") as Record<string, { section: string; until?: number }>;
    assert.deepEqual([placed["c1"], placed["c2"]].map((p) => [p?.section, p?.until]), [["snoozed", undefined], ["snoozed", undefined]], "a task row snoozes by its first chat, until it is unsnoozed");
    await assert.rejects(fake.callService("divergence/sidebar", "snooze", { taskId: "gone", until: null }), (error: { _tag?: string }) => error._tag === "UnknownRow");
    await fake.callService("divergence/sidebar", "unsnooze", { taskId: "t1" });
    await fake.callService("divergence/sidebar", "unsnooze", { taskId: "gone" });
    await fake.settle();
    const after = fake.storage.get("placedChats") as Record<string, { section: string }>;
    assert.equal(after["c1"]?.section, "snoozed");
    assert.equal(after["c2"], undefined, "the task row is back where its state puts it");
  } finally {
    await dispose();
  }
});

test("a finished chat keeps its last reply in the sidebar after a tool call", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(2) }]);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    fake.emit({ event: "agent", chatId: "c1", kind: { event: "text_delta", itemId: "a", text: "The work is done.", mode: "append" } });
    fake.emit({ event: "agent", chatId: "c1", kind: { event: "tool_call_started", id: "t", name: "Run", title: "Late command", kind: "execute", status: "completed" } });
    await fake.settle();
    assert.ok(fake.text().includes("The work is done."));
    assert.ok(!fake.text().includes("Late command"));
  } finally { await dispose(); }
});

test("a finished chat finds its last reply beyond the preview page", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(2) }]);
  const host = fake.api.host as unknown as { call: (method: string, params: { before?: number }) => Promise<unknown> };
  const original = host.call;
  const tools = Array.from({ length: 100 }, (_, i) => ({ id: `t${i}`, role: "tool", call: { id: `t${i}`, name: "Run", title: "A command", kind: "execute", status: "completed" } }));
  host.call = (method, params) => method === "host/chats.peek" ? Promise.resolve({ items: tools.slice(0, 20) })
    : method === "host/chats.transcript" ? Promise.resolve(params.before === undefined ? { items: tools, start: 1 } : { items: [{ id: "a", role: "assistant", text: "Earlier reply." }], start: 0 })
    : original(method, params);
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    await fake.settle();
    assert.ok(fake.text().includes("Earlier reply."));
  } finally { await dispose(); }
});

test("previews that cannot be read say so once, and a chat that changes is read again", async () => {
  const fake = fakeHost([
    { id: "c1", title: "First", at: day(2) },
    { id: "c2", title: "Second", at: day(1) },
  ]);
  fake.fail("host/chats.peek", "the transcript is locked");
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    await fake.settle();
    assert.equal(fake.peeks(), 2, "each row asked once");
    assert.deepEqual(fake.notices, ["Chat preview unavailable: the transcript is locked"]);
    await fake.settle();
    assert.equal(fake.peeks(), 2, "a failed read is not asked again at every draw");
    fake.pass("host/chats.peek");
    fake.touch("c1");
    await fake.settle();
    assert.equal(fake.peeks(), 3, "the chat that changed is read again");
  } finally {
    await dispose();
  }
});

// A read that failed after the agent had streamed a line used to show the
// notice and mark the streamed preview failed, so the next change of the
// chat threw that line away and read it again.
test("a preview read that fails after the agent streamed a line changes nothing", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(2) }]);
  fake.fail("host/chats.peek", "the transcript is locked");
  const release = fake.hold("host/chats.peek");
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    assert.equal(fake.peeks(), 1);
    fake.emit({ event: "agent", chatId: "c1", kind: { event: "text_delta", itemId: "a", text: "Reading the parser.\n", mode: "append" } });
    await fake.settle();
    release();
    await fake.settle();
    assert.deepEqual(fake.notices, [], "the streamed line already answers the read");
    fake.touch("c1");
    await fake.settle();
    assert.equal(fake.peeks(), 1, "the streamed preview is kept, not read again");
    assert.ok(fake.text().includes("Reading the parser."));
  } finally {
    await dispose();
  }
});

test("a first read that fails says so in place of the list, and the next event reads again", async () => {
  const fake = fakeHost([{ id: "c1", title: "First", at: day(1) }]);
  fake.fail("host/chats.list", "the store is locked");
  const dispose = activate(fake.api);
  try {
    await fake.settle();
    assert.ok(fake.text().includes("The chats could not be read: the store is locked"));
    fake.pass("host/chats.list");
    fake.emit({ event: "workspaces_changed" } as never);
    await fake.settle();
    assert.deepEqual(fake.list(), ["heading-open", "row-c1"]);
  } finally {
    await dispose();
  }
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.7latestNov 21, 2026>=5 <6100.9 KB4 permissionsListed
0.2.6Nov 16, 2026>=5 <6100.6 KB4 permissionsListed
0.2.5Nov 11, 2026>=5 <665.1 KB4 permissionsListed
0.2.4Nov 9, 2026>=5 <660.4 KB4 permissionsListed
0.2.3Oct 27, 2026>=2 <426.1 KB3 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.