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 divergence/chat@0.2.7
Permissions in 0.2.7
Files
notifications.test.ts10.1 KB
// When a chat earns a system notification: a turn that finishes or fails, an approval or a
// question, each announced once, never for a turn that ended before the plugin started, and
// posted with `unlessFocused` exactly when the chat is on screen (the kernel then posts it only
// while the window is not focused).
import assert from "node:assert/strict";
import test from "node:test";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { Events, KernelCallFailed } from "divergence/effect";
import type { AgentEventKind, KernelMethods, SettledRun } from "divergence";
import type { Layout } from "divergence/protocol";
import { InputLedger, withController } from "./testing.ts";
import { noteTask } from "./layout.ts";
import { Announced, announce, followNotifications, type Observed } from "./notifications.ts";
import type { Controller } from "./controller.ts";
const START = Date.parse("2026-11-04T10:00:00Z");
const run = (outcome: SettledRun["outcome"], fields: Partial<SettledRun> = {}): SettledRun => ({
id: "r1",
generation: 1,
outcome,
stoppedAt: "2026-11-04T10:05:00Z",
steering: false,
...fields,
});
const settled = (chatId: string, settledRun: SettledRun): Observed => ({
event: "run_settled",
chatId,
run: settledRun,
});
const agent = (chatId: string, kind: AgentEventKind, taskId?: string): Observed => ({
event: "agent",
chatId,
kind,
...(taskId ? { taskId } : {}),
});
const approval = (id: string) =>
({
event: "approval",
id,
toolCall: { id: "t", title: "Run ls", kind: "execute", status: "pending" },
options: [],
}) as unknown as AgentEventKind;
const question = (id: string) =>
({ event: "question", id, message: "Which one?", fields: [] }) as unknown as AgentEventKind;
test("a turn is announced when it finishes or fails, and not when you stopped it", () => {
const announced = new Announced(START);
assert.equal(announced.notice(settled("c1", run({ status: "completed" }))), "finished");
assert.equal(announced.notice(settled("c1", run({ status: "failed", message: "boom" }))), "failed");
const limit = { kind: "reset", resetsAt: "2026-11-04T11:00:00Z" } as unknown as SettledRun["usageLimit"];
assert.equal(
announced.notice(settled("c1", run({ status: "failed", message: "limit" }, { usageLimit: limit }))),
"limited",
);
assert.equal(announced.notice(settled("c1", run({ status: "cancelled" }))), null, "you stopped it yourself");
assert.equal(
announced.notice(settled("c1", run({ status: "cancelled" }, { steering: true }))),
null,
"a steer's stop is no ending",
);
});
test("a turn that ended before the plugin started is not announced when the host settles it", () => {
const announced = new Announced(START);
assert.equal(
announced.notice(settled("c1", run({ status: "completed" }, { stoppedAt: "2026-11-04T09:59:00Z" }))),
null,
);
});
test("only the settlement announces a turn's end, so a turn is never announced twice", () => {
const announced = new Announced(START);
assert.equal(
announced.notice(agent("c1", { event: "run_finished", outcome: { status: "completed" } } as AgentEventKind)),
null,
);
assert.equal(announced.notice(settled("c1", run({ status: "completed" }))), "finished");
});
test("an approval or a question is announced once while it waits", () => {
const announced = new Announced(START);
assert.equal(announced.notice(agent("c1", approval("a1"))), "approval");
assert.equal(announced.notice(agent("c1", approval("a1"))), null, "the agent repeats the same request");
assert.equal(announced.notice(agent("c1", question("q1"))), "question");
assert.equal(announced.notice(agent("c1", approval("a1"), "sub")), "approval", "a subagent's request is its own");
assert.equal(announced.notice(agent("c2", approval("a1"))), "approval", "another chat's request is its own");
announced.notice(agent("c1", { event: "approval_resolved", id: "a1" } as AgentEventKind));
assert.equal(announced.notice(agent("c1", approval("a1"))), "approval", "asked again after an answer");
announced.notice(settled("c1", run({ status: "completed" })));
assert.equal(announced.notice(agent("c1", question("q1"))), "question", "a new turn may reuse an id");
announced.notice({ event: "chat_removed", chatId: "c2" });
assert.equal(announced.notice(agent("c2", approval("a1"))), "approval");
});
type Shown = KernelMethods["notification.show"]["params"];
/** A controller whose kernel records `notification.show`, or fails it with `failure`. */
function withNotifications(
fn: (c: Controller, shown: Shown[], ledger: InputLedger) => Effect.Effect<void, unknown>,
failure?: string,
) {
const ledger = new InputLedger(["c1", "c2", "c3"]);
return withController(ledger, (c) => {
const shown: Shown[] = [];
Object.assign(c, {
kernel: {
call: (method: string, params: Shown) =>
failure
? Effect.fail(new KernelCallFailed({ method, message: failure }))
: Effect.sync(() => void shown.push(params)),
},
});
Object.assign(c.state.chats.c1!, { title: "Fix the build" });
return fn(c, shown, ledger).pipe(Effect.as(ledger));
});
}
const view = (c: Controller, route: string, chatId: string) =>
Object.assign(c.api.app, { state: () => ({ route, chatId }) });
const tabOf = (chatId: string) => ({ kind: "chat" as const, chatId });
const pane = (id: string, chatId: string): Layout => ({
kind: "pane",
id,
tabs: [tabOf(chatId)],
active: tabOf(chatId),
});
test("a chat on screen asks the kernel to stay quiet while the window is focused; any other chat does not", async () => {
await withNotifications((c, shown) =>
Effect.gen(function* () {
view(c, "chat", "c1");
yield* announce(c, "c1", "finished");
yield* announce(c, "c2", "approval");
assert.deepEqual(shown, [
{ chatId: "c1", title: "Chat finished", body: "Fix the build", unlessFocused: true },
{ chatId: "c2", title: "Approval needed", body: "New Chat", unlessFocused: false },
]);
shown.length = 0;
// c2 beside c1 in a split of the task on screen, c3 of the same task in the side split, and c4 of
// another task in the side split, which does not show beside this one.
const root: Layout = {
kind: "split",
id: "s",
direction: "row",
children: [
{ share: 0.5, layout: pane("p1", "c1") },
{ share: 0.5, layout: pane("p2", "c2") },
],
};
noteTask(c.state.layouts, { id: "t", layout: { root, focused: "p1" }, createdAt: "", updatedAt: "" });
c.state.layouts.homes.c3 = "t";
c.state.layouts.homes.c4 = "other";
c.state.chats.c4 = { ...c.state.chats.c3!, id: "c4" };
const sideRoot: Layout = {
kind: "split",
id: "side",
direction: "column",
children: [
{ share: 0.5, layout: pane("p3", "c3") },
{ share: 0.5, layout: pane("p4", "c4") },
],
};
c.state.layouts.side = {
layout: { root: sideRoot, focused: "p3" },
remembered: [],
open: true,
width: 400,
};
yield* announce(c, "c2", "question");
yield* announce(c, "c3", "failed");
yield* announce(c, "c4", "finished");
c.state.layouts.side = { ...c.state.layouts.side, open: false };
yield* announce(c, "c3", "failed");
view(c, "settings", "c1");
yield* announce(c, "c1", "finished");
assert.deepEqual(
shown.map((s) => [s.chatId, s.title, s.unlessFocused]),
[
["c2", "Input needed", true],
["c3", "Chat failed", true],
["c4", "Chat finished", false],
["c3", "Chat failed", false],
["c1", "Chat finished", false],
],
);
}),
);
});
test("nothing is posted with notifications off in Settings, or for an archived chat", async () => {
const ledger = await withNotifications((c, shown, ledger) =>
Effect.gen(function* () {
Object.assign(c.state.chats.c2!, { archived: true });
yield* announce(c, "c2", "finished");
ledger.settings.notifications = false;
yield* announce(c, "c1", "finished");
assert.deepEqual(shown, []);
}),
);
assert.deepEqual(ledger.notices, []);
});
test("an older app without notifications shows none and reports nothing; any other failure is reported", async () => {
await withNotifications((c) => announce(c, "c1", "finished"), "method not found: kernel/notification.show");
await withNotifications(
(c) =>
Effect.gen(function* () {
const failed = yield* Effect.flip(announce(c, "c1", "finished"));
assert.equal(failed.message, "the notification center is gone");
}),
"the notification center is gone",
);
});
/** Follows these host events, each delivered once to whoever follows its name, until the notices are posted. */
const follow = (c: Controller, list: Observed[]) => {
const events = {
all: Stream.fromIterable(list),
stream: (name: string) => Stream.fromIterable(list.filter((event) => event.event === name)),
};
return Effect.scoped(
followNotifications(c).pipe(
Effect.provideService(Events, events as unknown as Events["Service"]),
Effect.andThen(Effect.sleep("10 millis")),
),
);
};
test("the plugin follows the host's events and posts each notice once", async () => {
const events = [
agent("c2", approval("a1")),
agent("c2", approval("a1")),
agent("c1", { event: "run_finished", outcome: { status: "completed" } } as AgentEventKind),
settled("c1", run({ status: "completed" }, { stoppedAt: new Date(Date.now() + 1000).toISOString() })),
];
await withNotifications((c, shown) =>
Effect.gen(function* () {
view(c, "chat", "c1");
yield* follow(c, events);
assert.deepEqual(shown.map((s) => [s.chatId, s.title, s.unlessFocused]).sort(), [
["c1", "Chat finished", true],
["c2", "Approval needed", false],
]);
}),
);
const ledger = await withNotifications(
(c) => follow(c, [agent("c1", question("q1"))]),
"the notification center is gone",
);
assert.deepEqual(ledger.notices, ["The notification could not be shown: the notification center is gone"]);
});Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.9latest | Nov 21, 2026 | >=5 <6 | 349 KB | 5 permissions | Listed |
| 0.2.8 | Nov 16, 2026 | >=5 <6 | 348.6 KB | 5 permissions | Listed |
| 0.2.7 | Nov 11, 2026 | >=5 <6 | 314.3 KB | 5 permissions | Listed |
| 0.2.6 | Nov 9, 2026 | >=5 <6 | 306.2 KB | 5 permissions | Listed |
| 0.2.5 | Oct 27, 2026 | >=2 <4 | 178.6 KB | 5 permissions | Listed |
No comments yet.