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
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
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.5latest | Nov 21, 2026 | >=2 <4 | 174.6 KB | 5 permissions | Listed |
| 0.2.4 | Oct 25, 2026 | >=2 <4 | 174.2 KB | 5 permissions | Listed |
| 0.2.3 | Oct 24, 2026 | >=2 <4 | 165.4 KB | 5 permissions | Listed |
| 0.2.2 | Oct 23, 2026 | >=2 <4 | 165 KB | 5 permissions | Listed |
| 0.2.1 | Oct 6, 2026 | >=2 <3 | 111.8 KB | 5 permissions | Listed |
| 0.2.0 | Oct 5, 2026 | >=2 <3 | 105.1 KB | 5 permissions | Listed |
No comments yet.