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.8
Permissions in 0.2.8
Files
notifications.ts7.3 KB
// System notifications about chats (docs/features/chat/notifications.md). A turn that ends or
// fails, or stops for an approval or an answer, while the user cannot see its chat (the window
// is not focused, or the chat is not on screen) gets a notification naming the chat; the kernel
// posts it and opens the chat when it is clicked. A turn whose agent left background commands
// running is announced when they end or a minute after it stopped, whichever comes first, as the
// sidebar keeps that chat in Running until then. What is announced and how it reads follow
// t3code's notifications, in Divergence's words.
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { Events } from "divergence/effect";
import type { KernelCallFailed, PermissionNotGranted } from "divergence/effect";
import type { Chat, HostEvents, SettledRun } from "divergence";
import type { Controller } from "./controller.ts";
import { chatsOnScreen } from "./layout.ts";
import { activeChat, COMMANDS_HOLD_FOR_MS } from "../sdk/ui/status.ts";
/** Each notification's title; its body is the chat's title. */
export const TITLES = {
finished: "Chat finished",
failed: "Chat failed",
limited: "Usage limit reached",
approval: "Approval needed",
question: "Input needed",
} as const;
export type Notice = keyof typeof TITLES;
/** The host events notifications follow. */
export type Observed =
| HostEvents["run_settled"]
| HostEvents["agent"]
| HostEvents["chat_changed"]
| HostEvents["chat_removed"];
/** What was announced, so that nothing is announced twice. */
export class Announced {
/** The waiting requests of each chat already announced, by subagent and request id. */
private readonly asked = new Map<string, Set<string>>();
/** The turn's notice of each chat whose background commands still run, and when it is due regardless. */
private readonly held = new Map<string, { readonly notice: Notice; readonly until: number }>();
/** A turn that ended before the plugin started (one the host settles at launch) is old news. */
private readonly since: number;
/** How many background commands a chat runs now, as the host last counted them. */
private readonly commandsOf: (chatId: string) => number;
constructor(since = Date.now(), commandsOf: (chatId: string) => number = () => 0) {
this.since = since;
this.commandsOf = commandsOf;
}
/** What one event is news of, if anything. */
notice(event: Observed): Notice | null {
if (event.event === "run_settled") return this.settled(event.chatId, event.run);
if (event.event === "chat_changed") return this.changed(event.chat);
if (event.event === "chat_removed") {
this.asked.delete(event.chatId);
this.held.delete(event.chatId);
return null;
}
const kind = event.kind;
if (kind.event === "approval" || kind.event === "question")
return this.asks(event.chatId, kind.event, `${event.taskId ?? ""}/${kind.id}`);
if (kind.event === "approval_resolved" || kind.event === "question_resolved")
this.asked.get(event.chatId)?.delete(`${event.taskId ?? ""}/${kind.id}`);
return null;
}
/** The host settles each turn once: one that finished or failed is news, one you stopped is not. */
private settled(chatId: string, run: SettledRun): Notice | null {
this.asked.delete(chatId);
this.held.delete(chatId);
const stopped = Date.parse(run.stoppedAt);
if (stopped < this.since) return null;
const notice = run.outcome.status === "completed" ? "finished" : run.outcome.status === "failed" ? (run.usageLimit ? "limited" : "failed") : null;
if (!notice || this.commandsOf(chatId) === 0) return notice;
this.held.set(chatId, { notice, until: stopped + COMMANDS_HOLD_FOR_MS });
return null;
}
/** When the held notice of a chat is due if its commands still run then. */
heldUntil(chatId: string): number | undefined {
return this.held.get(chatId)?.until;
}
/** The notice held until `until`, once that minute is up, if it still waits (a later turn holds its own). */
due(chatId: string, until: number): Notice | null {
const held = this.held.get(chatId);
if (held?.until !== until) return null;
this.held.delete(chatId);
return held.notice;
}
/** A held notice is due when the chat's commands end; a new turn makes it old news. */
private changed(chat: Chat): Notice | null {
const held = this.held.get(chat.id);
if (!held) return null;
if (activeChat(chat.status)) this.held.delete(chat.id);
else if (!chat.working?.commands) {
this.held.delete(chat.id);
return held.notice;
}
return null;
}
/** The same request again, as an agent repeats one it still waits on, is not news. */
private asks(chatId: string, kind: "approval" | "question", key: string): Notice | null {
const asked = this.asked.get(chatId) ?? new Set<string>();
this.asked.set(chatId, asked);
if (asked.has(key)) return null;
asked.add(key);
return kind;
}
}
/** An app older than notifications has no `notification.show`; it shows none. */
const olderApp = (error: KernelCallFailed | PermissionNotGranted): boolean =>
error._tag === "KernelCallFailed" && /method not found|unknown kernel method/.test(error.message);
/**
* Posts a notice about a chat, unless notifications are off in Settings or the chat is archived.
* Whether the window is focused is the kernel's to tell: for a chat on screen it posts only while
* the window is not focused (`unlessFocused`), and for any other chat either way.
*/
export const announce = Effect.fn("Chat.announce")(function* (c: Controller, chatId: string, notice: Notice) {
const chat = c.state.chats[chatId];
if (!chat || chat.archived || c.api.settings.get("notifications") === false) return;
const unlessFocused = chatsOnScreen(c).has(chatId);
yield* c.kernel
.call("notification.show", { chatId, title: TITLES[notice], body: c.titleOf(chat), unlessFocused })
.pipe(Effect.catchIf(olderApp, () => Effect.void));
});
export const followNotifications = Effect.fn("Chat.followNotifications")(function* (c: Controller) {
const events = yield* Events;
const announced = new Announced(Date.now(), (chatId) => c.state.chats[chatId]?.working?.commands ?? 0);
const post = (chatId: string, notice: Notice) =>
announce(c, chatId, notice).pipe(
Effect.catch((error) => c.notify.error(`The notification could not be shown: ${error.message}`)),
);
// A held notice waits for its minute, unless its commands end or a new turn starts first.
const later = (chatId: string, until: number) =>
Effect.sleep(Math.max(0, until - Date.now())).pipe(
Effect.andThen(() => {
const notice = announced.due(chatId, until);
return notice ? post(chatId, notice) : Effect.void;
}),
);
const observe = (event: Observed) => {
const chatId = event.event === "chat_changed" ? event.chat.id : event.chatId;
const notice = announced.notice(event);
const until = event.event === "run_settled" ? announced.heldUntil(chatId) : undefined;
const work = notice ? post(chatId, notice) : until !== undefined ? later(chatId, until) : null;
return work ? Effect.forkIn(work, c.scope, { startImmediately: true }) : Effect.void;
};
for (const name of ["run_settled", "agent", "chat_changed", "chat_removed"] as const)
yield* events.stream(name).pipe(Stream.runForEach(observe), Effect.forkScoped({ startImmediately: true }));
});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.