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 convergence/sidebar@0.2.3
Permissions in 0.2.3
Files
chat.test.ts23 KB
// The sidebar follows the chat plugin's queue and draft titles through
// the convergence/chat service. Real activation with a canned chat
// client: the initial read fills the rows, events update them, and without
// a provider the rows show the stored titles.
import assert from "node:assert/strict";
import { test } from "node:test";
import type {
Api,
AppState,
AppStatePatch,
Chat,
HostEvent,
RenderResult,
SlotOptions,
ViewContext,
} from "convergence";
import { ui } from "convergence";
import { testLayer } from "convergence/effect/testing";
import { activate } from "./main.ts";
const tick = () => new Promise<void>((resolve) => setImmediate(resolve));
const stable = (value: unknown) =>
JSON.stringify(value, (_key, item: unknown) => (typeof item === "function" ? "@handler" : item));
function findNode(value: unknown, id: string): Record<string, unknown> | undefined {
if (!value || typeof value !== "object") return;
if (Array.isArray(value)) return value.map((child) => findNode(child, id)).find(Boolean);
const node = value as Record<string, unknown>;
return node.id === id ? node : findNode(node.children, id);
}
function fakeApi(withChat: boolean) {
let state: AppState = { workspaceId: "w1" };
const appListeners = new Set<(state: AppState) => void>();
const views: { render: (ctx: ViewContext<object>) => RenderResult; active: boolean; state: object }[] = [];
const listeners = new Map<string, Set<(event: HostEvent) => unknown>>();
const chatCalls: { method: string; params: unknown }[] = [];
const creates: unknown[] = [];
const chatSubs = new Map<string, Set<(payload: unknown) => void>>();
let dirty = true;
let pendingDefaultSave: Promise<object> | undefined;
let queued: string[] = ["c1"];
let drafts: Record<string, string> = { c1: "Typed!" };
let pendingSubmit: Promise<null> | undefined;
const notices: string[] = [];
const update = (patch: AppStatePatch) => {
state = {
...state,
...patch,
workspaceId: patch.workspaceId === null ? undefined : (patch.workspaceId ?? state.workspaceId),
chatId: patch.chatId === null ? undefined : (patch.chatId ?? state.chatId),
route: patch.route ?? state.route,
shared: { ...state.shared, ...patch.shared },
};
dirty = true;
for (const listener of appListeners) listener(state);
};
const chatClient = {
queued: Object.assign(async () => [...queued], {
// The Effect adapter calls through `result`, never the direct call.
result: async () => {
chatCalls.push({ method: "queued", params: {} });
return { ok: true as const, value: [...queued] };
},
}),
draftTitles: Object.assign(async () => ({ ...drafts }), {
result: async () => {
chatCalls.push({ method: "draftTitles", params: {} });
return { ok: true as const, value: { ...drafts } };
},
}),
submitDraft: Object.assign(async () => null, {
result: async (params: { chatId: string; queue: boolean }) => {
chatCalls.push({ method: "submitDraft", params });
return { ok: true as const, value: await (pendingSubmit ?? Promise.resolve(null)) };
},
}),
unqueue: Object.assign(async () => null, {
result: async (params: { chatId: string }) => {
chatCalls.push({ method: "unqueue", params });
return { ok: true as const, value: null };
},
}),
on: (event: string, fn: (payload: unknown) => void) => {
const key = `convergence/chat|${event}`;
const set = chatSubs.get(key) ?? new Set<(payload: unknown) => void>();
chatSubs.set(key, set);
set.add(fn);
return () => {
set.delete(fn);
};
},
};
const updates: unknown[] = [];
const hostCall = async (method: string, params: unknown) => {
if (method === "host/chats.update") {
updates.push(params);
return {};
}
if (method === "host/storage.get") return { value: undefined };
if (method === "host/storage.set") return pendingDefaultSave ?? {};
if (method === "host/workspaces.add") {
const { path } = params as { path: string };
const workspace = {
id: `w${workspaces.length + 1}`,
name: path.split("/").pop()!,
path,
position: workspaces.length,
};
workspaces.push(workspace);
return workspace;
}
if (method === "host/chats.create") {
creates.push(params);
const { workspaceId, agentId } = params as { workspaceId: string; agentId: string };
const chat: Chat = { ...chats[0]!, id: `c${chats.length + 1}`, workspaceId, agentId };
chats.push(chat);
return chat;
}
throw new Error(`Unexpected host method ${method} ${JSON.stringify(params)}`);
};
const commands = new Map<string, (api: Api) => unknown>();
const actions = new Map<string, unknown>();
const kernelCall = async (method: string, params: unknown) => {
throw new Error(`Unexpected kernel method ${method} ${JSON.stringify(params)}`);
};
const broker = testLayer();
const workspaces = [{ id: "w1", name: "Workspace", path: "/fixture", position: 0 }];
const chats: Chat[] = [
{
id: "c1",
workspaceId: "w1",
agentId: "a",
title: "New Chat",
createdAt: "",
updatedAt: "",
archived: false,
options: {},
status: "idle",
},
];
let pendingList: Promise<{ chats: Chat[] }> | undefined;
const tasks = [
{
id: "t1",
workspaceId: "w1",
kind: "chat",
userTitle: false,
completed: false,
pinned: false,
createdAt: "",
updatedAt: "",
sortOrder: 0,
chatIds: ["c1"],
},
];
const promiseApi = {
workspaces: { list: async () => ({ workspaces }) },
chats: {
list: async () => {
const pending = pendingList;
pendingList = undefined;
return pending ?? { chats: chats.map((chat) => ({ ...chat })) };
},
transcript: async () => ({ items: [] }),
},
tasks: { list: async () => ({ tasks }) },
agents: { list: async () => ({ agents: [{ id: "a", name: "A" }] }) },
};
// This assertion describes a local fake; unused API methods fail rather than impersonating external replies.
const api = new Proxy(
{
...broker.api,
plugin: "sidebar",
id: "convergence/sidebar",
ui,
services: {
provide: async () => ({ emit: () => {}, remove: () => {} }),
get: (name: string) => {
if (name === "convergence/chat" && withChat) return chatClient;
throw new Error(`no provider for ${name}`);
},
available: (name: string) => name === "convergence/chat" && withChat,
when: (name: string, fn: (client: unknown) => void) => {
fn(name === "convergence/chat" && withChat ? chatClient : undefined);
return () => {};
},
},
host: { ...broker.api.host, ...promiseApi, call: hostCall, kernel: kernelCall },
app: {
state: () => state,
update,
share: (key: string, value: unknown) => update({ shared: { [key]: value } }),
select: (chatId: string, workspaceId: string) => update({ chatId, workspaceId }),
route: (route: string) => update({ route }),
onChange: (fn: (state: AppState) => void) => {
appListeners.add(fn);
return () => {
appListeners.delete(fn);
};
},
},
slot: (slot: string, render: (ctx: ViewContext<object>) => RenderResult, _options?: SlotOptions) => {
const view = { render, active: true, state: {} };
views.push(view);
dirty = true;
return {
id: views.length,
update: () => {
dirty = true;
},
remove: () => {
view.active = false;
},
};
},
on: (name: string, fn: (event: HostEvent) => unknown) => {
const subscribers = listeners.get(name) ?? new Set();
listeners.set(name, subscribers);
subscribers.add(fn);
return () => {
subscribers.delete(fn);
};
},
command: (command: { id: string; run: (api: Api) => unknown }) => {
commands.set(command.id, command.run);
return { remove() {} };
},
commandAction: (id: string, action: unknown) => {
if (!commands.has(id)) return false;
actions.set(id, action);
return true;
},
pickFolder: async () => ({ path: "/fixture/tide-pool" }),
notify: (message: string) => {
notices.push(message);
},
focus: () => {},
},
{
get(target, key, receiver) {
if (Reflect.has(target, key)) return Reflect.get(target, key, receiver);
throw new Error(`Unexpected API ${String(key)}`);
},
},
) as unknown as Api;
const render = () =>
views
.filter((view) => view.active)
.map((view) =>
view.render({
state: view.state,
app: state,
plugin: "sidebar",
update: () => {
dirty = true;
},
}),
);
let trees: RenderResult[] = [];
const settle = async () => {
for (let round = 0; round < 50; round++) {
await tick();
if (!dirty) {
await tick();
if (!dirty) return;
}
dirty = false;
trees = render();
}
throw new Error("sidebar did not settle");
};
return {
api,
actions,
app: () => state,
run: (id: string) => commands.get(id)!(api),
chatCalls,
creates,
updates,
notices,
node: (id: string) => findNode(trees, id),
invoke: (id: string, event: string, payload: unknown) => {
const node = findNode(trees, id);
assert.ok(node, id);
const handler = node[event];
assert.equal(typeof handler, "function", event);
(handler as (payload: unknown) => void)(payload);
},
holdSubmit: () => {
const gate = Promise.withResolvers<null>();
pendingSubmit = gate.promise;
return () => {
pendingSubmit = undefined;
gate.resolve(null);
};
},
update,
settle,
trees: () => stable(trees),
chats,
hostEvent: (event: HostEvent) => {
for (const fn of listeners.get(event.event) ?? []) fn(event);
},
holdList: () => {
const snapshot = chats.map((chat) => ({ ...chat }));
let release!: () => void;
pendingList = new Promise((resolve) => {
release = () => {
pendingList = undefined;
resolve({ chats: snapshot });
};
});
return release;
},
holdDefaultSave: () => {
const pending = Promise.withResolvers<object>();
pendingDefaultSave = pending.promise;
return () => {
pendingDefaultSave = undefined;
pending.resolve({});
};
},
chatEvent: (event: string, payload: unknown) => {
for (const fn of chatSubs.get(`convergence/chat|${event}`) ?? []) fn(payload);
},
providerData: (next: { queued?: string[]; drafts?: Record<string, string> }) => {
if (next.queued) queued = next.queued;
if (next.drafts) drafts = next.drafts;
},
};
}
test("draft Play swaps with Cmd, submits the clicked chat without selecting it, and blocks repeat clicks", async () => {
const fake = fakeApi(true);
fake.providerData({ queued: [] });
fake.update({ chatId: "elsewhere" });
const dispose = activate(fake.api);
const modifiers = (meta: boolean) => ({ modifiers: { meta, ctrl: false, alt: false, shift: false } });
try {
await fake.settle();
assert.equal(fake.node("play-c1")?.icon, "play");
assert.equal(fake.node("glyph-c1"), undefined, "a draft has no completion checkbox");
fake.invoke("sidebar", "onModifiersChanged", modifiers(true));
await fake.settle();
assert.equal(fake.node("play-c1")?.icon, "list-plus");
fake.invoke("sidebar", "onModifiersChanged", modifiers(false));
await fake.settle();
assert.equal(fake.node("play-c1")?.icon, "play");
const release = fake.holdSubmit();
// Click-time modifiers decide intent even before the icon redraw arrives.
fake.invoke("play-c1", "onClick", modifiers(true));
fake.invoke("play-c1", "onClick", modifiers(true));
await fake.settle();
assert.equal(fake.node("play-c1")?.disabled, true);
assert.equal(fake.node("play-c1")?.loading, true);
assert.deepEqual(
fake.chatCalls.filter((call) => call.method === "submitDraft"),
[{ method: "submitDraft", params: { chatId: "c1", queue: true } }],
);
assert.equal(fake.app().chatId, "elsewhere");
release();
await fake.settle();
assert.equal(fake.node("play-c1")?.disabled, false);
fake.invoke("play-c1", "onClick", modifiers(false));
await fake.settle();
assert.deepEqual(fake.chatCalls.at(-1), { method: "submitDraft", params: { chatId: "c1", queue: false } });
assert.equal(fake.app().chatId, "elsewhere");
assert.deepEqual(fake.notices, []);
fake.chats[0] = { ...fake.chats[0], sessionId: "started" };
fake.hostEvent({ event: "chat_changed", chat: { ...fake.chats[0] } });
await fake.settle();
assert.ok(fake.node("glyph-c1"), "started chats keep their completion action");
assert.equal(fake.node("play-c1"), undefined);
} finally {
await dispose();
}
});
test("New chat selects the returned draft before settings/list reads and survives an older list", async () => {
const fake = fakeApi(false);
const dispose = activate(fake.api);
try {
await fake.settle();
const releaseSave = fake.holdDefaultSave();
const releaseList = fake.holdList();
fake.hostEvent({ event: "agents_changed" });
await fake.settle();
fake.run("sidebar.newChat");
await fake.settle();
assert.equal(fake.app().chatId, "c2", "settings and list latency must not block selection");
assert.deepEqual(
fake.app().shared?.selectedChat,
fake.chats[1],
"selection includes metadata for the first chat frame",
);
assert.ok(fake.trees().includes('"id":"row-c2"'), "returned draft is already in the sidebar");
releaseSave();
releaseList();
await fake.settle();
assert.ok(fake.trees().includes('"id":"row-c2"'), "an old list cannot erase the newly created draft");
} finally {
await dispose();
}
});
test("the queued chats and draft titles come from the chat service", async () => {
const fake = fakeApi(true);
const dispose = activate(fake.api);
try {
await fake.settle();
// The initial read fills the rows: c1 is queued with a typed title.
assert.ok(fake.chatCalls.some((call) => call.method === "queued"));
assert.ok(fake.chatCalls.some((call) => call.method === "draftTitles"));
assert.ok(fake.trees().includes("Typed!"));
assert.ok(fake.trees().includes("Queued"));
// A queued chat is one line with a button that takes it out of the queue.
assert.equal(fake.node("unqueue-c1")?.icon, "list-minus");
assert.equal(fake.node("glyph-c1"), undefined);
assert.equal(fake.node("row-c1")?.sublabel, undefined);
fake.invoke("unqueue-c1", "onClick", undefined);
await fake.settle();
assert.deepEqual(fake.chatCalls.at(-1), { method: "unqueue", params: { chatId: "c1" } });
// Events update the rows without shared state.
fake.providerData({ queued: [], drafts: {} });
fake.chatEvent("queuedChanged", []);
fake.chatEvent("draftTitlesChanged", {});
await fake.settle();
assert.ok(!fake.trees().includes("Typed!"));
assert.ok(!fake.trees().includes("Queued"));
assert.equal(fake.node("unqueue-c1"), undefined);
assert.ok(fake.trees().includes("New Chat"));
} finally {
await dispose();
}
});
test("without the chat plugin the rows show the stored titles", async () => {
const fake = fakeApi(false);
const dispose = activate(fake.api);
try {
await fake.settle();
assert.deepEqual(fake.chatCalls, []);
assert.ok(fake.trees().includes("New Chat"));
assert.ok(!fake.trees().includes("Queued"));
} finally {
await dispose();
}
});
test("a list refresh cannot mark a new running turn finished", async () => {
const fake = fakeApi(false);
fake.chats[0] = { ...fake.chats[0]!, sessionId: "session", updatedAt: "2026-10-04T17:00:00Z" };
const dispose = activate(fake.api);
try {
await fake.settle();
fake.hostEvent({ event: "agent", chatId: "c1", kind: { event: "run_finished", outcome: { status: "completed" } } });
await fake.settle();
assert.ok(fake.trees().includes('"label":"Finished"'));
const release = fake.holdList();
fake.hostEvent({ event: "agents_changed" });
await fake.settle();
const running: Chat = { ...fake.chats[0]!, status: "running", updatedAt: "2026-10-04T17:01:00Z" };
fake.hostEvent({ event: "chat_changed", chat: running });
fake.hostEvent({
event: "agent",
chatId: "c1",
kind: {
event: "tool_call_started",
id: "tool",
name: "Bash",
kind: "execute",
title: "Run tests",
status: "running",
},
});
await fake.settle();
assert.ok(fake.trees().includes('"label":"Running"'));
release();
await fake.settle();
assert.ok(
fake.trees().includes('"label":"Running"'),
"a stale idle snapshot must not replace the live running state",
);
assert.ok(!fake.trees().includes('"label":"Finished"'));
} finally {
await dispose();
}
});
for (const status of ["idle", "failed", "waiting_approval", "waiting_question"] as const) {
test(`a stale running list cannot overwrite ${status}`, async () => {
const fake = fakeApi(false);
fake.chats[0] = { ...fake.chats[0]!, sessionId: "s", status: "running", updatedAt: "2026-10-04T17:00:00Z" };
const dispose = activate(fake.api);
try {
await fake.settle();
const release = fake.holdList();
fake.hostEvent({ event: "agents_changed" });
await fake.settle();
const current: Chat = { ...fake.chats[0]!, status, updatedAt: "2026-10-04T17:01:00Z" };
fake.hostEvent({ event: "chat_changed", chat: current });
if (status === "idle" || status === "failed")
fake.hostEvent({
event: "agent",
chatId: "c1",
kind: { event: "run_finished", outcome: { status: "completed" } },
});
release();
await fake.settle();
const label = status.startsWith("waiting_") ? "Needs you" : "Finished";
assert.ok(fake.trees().includes(`"label":"${label}"`));
assert.ok(!fake.trees().includes('"label":"Running"'));
} finally {
await dispose();
}
});
}
test("a newer list still updates a chat, including metadata at the same timestamp", async () => {
const fake = fakeApi(false);
fake.chats[0] = { ...fake.chats[0]!, sessionId: "s", status: "running", updatedAt: "2026-10-04T17:00:00Z" };
const dispose = activate(fake.api);
try {
await fake.settle();
fake.chats[0] = { ...fake.chats[0]!, title: "Updated title", status: "idle", updatedAt: "2026-10-04T17:01:00Z" };
fake.hostEvent({ event: "agents_changed" });
await fake.settle();
assert.ok(fake.trees().includes("Updated title"));
assert.ok(!fake.trees().includes('"label":"Running"'));
fake.chats[0] = { ...fake.chats[0]!, title: "Same time metadata" };
fake.hostEvent({ event: "agents_changed" });
await fake.settle();
assert.ok(fake.trees().includes("Same time metadata"));
} finally {
await dispose();
}
});
test("adding a folder shows it alone and opens a draft there", async () => {
const fake = fakeApi(false);
const dispose = activate(fake.api);
try {
await fake.settle();
await fake.run("sidebar.addWorkspace");
await fake.settle();
const draft = fake.chats.find((chat) => chat.workspaceId === "w2");
assert.ok(draft, "a draft was created in the new workspace");
assert.equal(fake.app().workspaceId, "w2");
assert.equal(fake.app().chatId, draft.id);
} finally {
await dispose();
}
});
test("New chat from a draft with a typed or queued prompt opens another draft", async () => {
const fake = fakeApi(true);
fake.providerData({ queued: ["c1"], drafts: { c2: "Typed!" } });
const dispose = activate(fake.api);
try {
await fake.settle();
await fake.run("sidebar.newChat");
await fake.settle();
assert.deepEqual(fake.creates, [{ workspaceId: "w1", agentId: "a", inUse: ["c2", "c1"] }]);
} finally {
await dispose();
}
});
test("a chat whose turn failed says Failed, not Finished, on its row", async () => {
const fake = fakeApi(false);
fake.chats[0] = { ...fake.chats[0]!, sessionId: "session", status: "running", updatedAt: "2026-10-04T17:00:00Z" };
const dispose = activate(fake.api);
try {
await fake.settle();
fake.hostEvent({ event: "chat_changed", chat: { ...fake.chats[0]!, status: "failed", updatedAt: "2026-10-04T17:01:00Z" } });
fake.hostEvent({
event: "agent",
chatId: "c1",
kind: { event: "run_finished", outcome: { status: "failed", message: "This API key has expired." } },
});
await fake.settle();
assert.ok(fake.trees().includes('"label":"Finished"'), "it is in Finished");
assert.ok(fake.trees().includes('"sublabel":"Failed'), fake.trees());
assert.ok(!fake.trees().includes('"sublabel":"Finished'));
} finally {
await dispose();
}
});
test("Cmd+1…9 declare the chat each opens, and follow the list", async () => {
const fake = fakeApi(false);
const dispose = activate(fake.api);
try {
await fake.settle();
assert.deepEqual(fake.actions.get("sidebar.openChat1"), { chatId: "c1", workspaceId: "w1", route: "chat" });
assert.equal(fake.actions.get("sidebar.openChat2"), null);
await fake.run("sidebar.newChat");
await fake.settle();
const listed = [fake.actions.get("sidebar.openChat1"), fake.actions.get("sidebar.openChat2")];
assert.ok(listed.every((action) => action && typeof action === "object"), JSON.stringify(listed));
} finally {
await dispose();
}
});
test("Cmd+W archives a draft, dequeues and archives a queued chat, and otherwise marks the chat complete", async () => {
const fake = fakeApi(true);
fake.providerData({ queued: ["c2"], drafts: {} });
fake.chats.push(
{ ...fake.chats[0]!, id: "c2" },
{ ...fake.chats[0]!, id: "c3", sessionId: "session", updatedAt: "2026-10-04T17:00:00Z" },
);
const dispose = activate(fake.api);
try {
await fake.settle();
fake.update({ chatId: "c1" });
await fake.run("sidebar.closeChat");
await fake.settle();
assert.deepEqual(fake.updates, [{ chatId: "c1", archived: true }]);
assert.notEqual(fake.app().chatId, "c1", "the archived draft gives the screen to another chat");
fake.update({ chatId: "c2" });
await fake.run("sidebar.closeChat");
await fake.settle();
assert.deepEqual(fake.chatCalls.at(-1), { method: "unqueue", params: { chatId: "c2" } });
assert.deepEqual(fake.updates.at(-1), { chatId: "c2", archived: true });
fake.update({ chatId: "c3" });
await fake.run("sidebar.closeChat");
await fake.settle();
assert.deepEqual(fake.updates.at(-1), { chatId: "c3", completed: true });
assert.equal(fake.app().chatId, "c3", "a completed chat stays on screen");
await fake.run("sidebar.closeChat");
await fake.settle();
assert.equal(fake.updates.length, 3, "a complete chat is not unchecked");
} finally {
await dispose();
}
});
No comments yet.