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

Permissions in 0.2.6

  • 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

notifications.test.ts9.5 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, and c3 in the side split.
      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.side = {
        layout: { root: pane("p3", "c3"), focused: "p3" },
        remembered: [],
        open: true,
        width: 400,
      };
      yield* announce(c, "c2", "question");
      yield* announce(c, "c3", "failed");
      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],
          ["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

VersionPublishedPlugin APISizePermissionsStatus
0.2.9latestNov 21, 2026>=5 <6349 KB5 permissionsListed
0.2.8Nov 16, 2026>=5 <6348.6 KB5 permissionsListed
0.2.7Nov 11, 2026>=5 <6314.3 KB5 permissionsListed
0.2.6Nov 9, 2026>=5 <6306.2 KB5 permissionsListed
0.2.5Oct 27, 2026>=2 <4178.6 KB5 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.