Official
settings
Built-in settings 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/settings@0.2.3
Permissions in 0.2.3
Files
upkeep.ts12.4 KB
// The update row at the foot of the sidebar: every enabled agent whose own
// program is behind, a new Divergence and new default plugins, in one place.
// An update never cuts off work: one asked for while its agent runs (or,
// for the app and the plugins, while any chat runs) waits and starts by
// itself once the runs end. One installer runs at a time. A version can be
// skipped, and the whole row put off until tomorrow.
import * as Effect from "effect/Effect";
import * as Result from "effect/Result";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as z from "zod";
import { Host, Kernel, Notify, Services, Storage } from "divergence/effect";
import type { AgentInfo, Chat, ChatStatus, UpdateStatus, ViewHandle } from "divergence";
import type { Terminal } from "../terminal/contract.ts";
/// What the button of an item does: install it here, run its command in a
/// terminal, nothing (the user updates it the way they installed it), or
/// install the app and restart.
export type Action = "update" | "terminal" | "manual" | "restart";
export interface UpdateItem {
/// The agent's id, `app` or `plugins`.
readonly id: string;
readonly name: string;
/// The agent's mark (inline SVG).
readonly icon: string | null;
readonly from: string | null;
readonly to: string;
readonly action: Action;
readonly command: string | null;
/// An agent's id; the app and the plugins wait for every chat.
readonly agentId: string | null;
}
export type Job =
| { readonly state: "waiting" }
| { readonly state: "updating" }
| { readonly state: "terminal" }
| { readonly state: "failed"; readonly message: string };
export const Dismissals = z.object({
/// The version skipped, by item id.
skipped: z.record(z.string(), z.string()),
/// The row stays away until then (epoch milliseconds).
snoozedUntil: z.number().nullable(),
});
export type Dismissals = z.infer<typeof Dismissals>;
export const SNOOZE = 24 * 60 * 60 * 1000;
const STORAGE_KEY = "upkeep";
// How long the list stays after the pointer leaves the row and the list,
// so the way from one to the other does not close it.
const HOVER_GRACE = "150 millis";
const BUSY: ReadonlySet<ChatStatus> = new Set(["running", "waiting_approval", "waiting_question"]);
type Agent = AgentInfo & { readonly enabled: boolean };
/// Everything that is behind, agents first in the host's order.
export function updateItems(agents: readonly Agent[], updates: UpdateStatus | null): UpdateItem[] {
const out: UpdateItem[] = [];
for (const agent of agents) {
const m = agent.maintenance;
if (!agent.enabled || !m?.latestVersion || m.latestVersion === m.installedVersion) continue;
out.push({
id: agent.id,
name: agent.name,
icon: agent.icon ?? null,
from: m.installedVersion ?? null,
to: m.latestVersion,
action: m.canUpdate ? "update" : m.command ? "terminal" : "manual",
command: m.command ?? null,
agentId: agent.id,
});
}
if (updates?.enabled && updates.pluginUpdate)
out.push({
id: "plugins",
name: "Default plugins",
icon: null,
from: updates.plugins ? `build ${updates.plugins.build}` : null,
to: `build ${updates.pluginUpdate.build}`,
action: "update",
command: null,
agentId: null,
});
if (updates?.enabled && updates.appUpdate)
out.push({
id: "app",
name: "Divergence",
icon: null,
from: updates.appVersion,
to: updates.appUpdate.version,
action: "restart",
command: null,
agentId: null,
});
return out;
}
/// The items the row shows: none while it is put off, and none skipped at
/// their version. An item with work under way always shows.
export function shownItems(
items: readonly UpdateItem[],
dismissals: Dismissals,
jobs: Readonly<Record<string, Job>>,
now: number,
): UpdateItem[] {
const snoozed = dismissals.snoozedUntil !== null && now < dismissals.snoozedUntil;
return items.filter((item) => jobs[item.id] || (!snoozed && dismissals.skipped[item.id] !== item.to));
}
/// Whether an update would cut off a run: one of the agent's own, or any
/// at all for the app and the plugins, which restart everything.
export function blocked(item: UpdateItem, chats: Iterable<Chat>): boolean {
for (const chat of chats) {
if (!BUSY.has(chat.status)) continue;
if (item.agentId === null || chat.agentId === item.agentId) return true;
}
return false;
}
/// "0.48.0 → 0.50.1", or the new version alone when the old one is unknown.
export function versionLine(item: UpdateItem): string {
return item.from ? `${item.from} → ${item.to}` : item.to;
}
export interface UpkeepState {
agents: readonly Agent[];
updates: UpdateStatus | null;
chats: Map<string, Chat>;
jobs: Record<string, Job>;
dismissals: Dismissals;
open: boolean;
}
export const makeUpkeep = Effect.fn("Upkeep.make")(function* () {
const host = yield* Host;
const kernel = yield* Kernel;
const notify = yield* Notify;
const storage = yield* Storage;
const services = yield* Services;
const scope = yield* Scope.Scope;
// Two installers at once can trip over each other (two global npm
// installs into one prefix), and the app's restart must come last.
const installer = yield* Semaphore.make(1);
const state: UpkeepState = {
agents: [],
updates: null,
chats: new Map(),
jobs: {},
dismissals: { skipped: {}, snoozedUntil: null },
open: false,
};
const views: ViewHandle[] = [];
const items = () => updateItems(state.agents, state.updates);
const shown = () => shownItems(items(), state.dismissals, state.jobs, Date.now());
// Where the pointer is, for the list that opens on hover.
const pointer = { row: false, list: false };
// The list closes with its last item, so the next one does not open it.
// A row or list that goes away under the pointer sends no leave.
const redraw = () => {
if (state.open && !shown().length) state.open = false;
if (!shown().length) pointer.row = false;
if (!state.open) pointer.list = false;
for (const view of views) view.update();
};
const loadAgents = Effect.fn("Upkeep.loadAgents")(function* () {
state.agents = (yield* host.call("host/agents.all", {})).agents;
redraw();
});
const loadUpdates = Effect.fn("Upkeep.loadUpdates")(function* () {
state.updates = yield* host.call("host/updates.status", {});
redraw();
});
const load = Effect.fn("Upkeep.load")(function* () {
const [agents, updates, chats, dismissals] = yield* Effect.all(
[
host.call("host/agents.all", {}),
host.call("host/updates.status", {}),
host.call("host/chats.list", {}),
storage.get(STORAGE_KEY, Dismissals).pipe(Effect.catchTag("ParseFailed", () => Effect.succeed(undefined))),
],
{ concurrency: "unbounded" },
);
state.agents = agents.agents;
state.updates = updates;
state.chats = new Map(chats.chats.map((chat) => [chat.id, chat]));
if (dismissals) state.dismissals = dismissals;
redraw();
});
const save = () => storage.set(STORAGE_KEY, state.dismissals);
// The work itself. After an agent's update the agent is read again
// before its job goes, so the row never shows the old gap in between.
const install = Effect.fn("Upkeep.install")(function* (item: UpdateItem) {
if (item.id === "app") {
const { restart } = yield* host.call("host/updates.install_app", {});
if (restart) yield* kernel.call("quit", {});
return null;
}
if (item.id === "plugins") {
const { report, chatId } = yield* host.call("host/updates.apply_plugins", {});
yield* loadUpdates();
if (chatId) return "An agent is merging the plugins you changed in the Plugins workspace.";
const changed = report.updated.length + report.added.length + report.removed.length;
return changed ? `Plugins updated (${changed} changed).` : null;
}
yield* host.call("host/agents.update", { agentId: item.id });
yield* loadAgents();
return `${item.name} updated to ${item.to}.`;
});
const perform = Effect.fn("Upkeep.perform")(function* (item: UpdateItem) {
state.jobs[item.id] = { state: "updating" };
redraw();
const done = yield* installer.withPermits(1)(install(item)).pipe(Effect.result);
if (Result.isFailure(done)) {
state.jobs[item.id] = { state: "failed", message: done.failure.message };
yield* notify.error(`${item.name}: ${done.failure.message}`);
} else {
delete state.jobs[item.id];
if (done.success) yield* notify.info(done.success);
}
redraw();
});
const start = (item: UpdateItem) => Effect.forkIn(perform(item), scope, { startImmediately: true });
const runInTerminal = Effect.fn("Upkeep.runInTerminal")(function* (item: UpdateItem) {
if (!item.command) return;
const terminal = yield* services.client<typeof Terminal>("divergence/terminal");
const ran = yield* terminal.run({ command: item.command, title: `Update ${item.name}` }).pipe(Effect.result);
if (Result.isFailure(ran)) return yield* notify.error(`Cannot open a terminal: ${ran.failure.message}`);
state.jobs[item.id] = { state: "terminal" };
state.open = false;
redraw();
});
/// The item's button: at once when nothing would be cut off, else once
/// the runs in its way end.
const request = Effect.fn("Upkeep.request")(function* (item: UpdateItem) {
if (item.action === "manual") return;
if (item.action === "terminal") return yield* runInTerminal(item);
if (blocked(item, state.chats.values())) {
state.jobs[item.id] = { state: "waiting" };
redraw();
return;
}
yield* start(item);
});
/// Every item one press installs, the app's restart aside: that one
/// closes the window, so it stays its own choice.
const requestAll = Effect.fn("Upkeep.requestAll")(function* () {
for (const item of shown()) {
const job = state.jobs[item.id];
if (item.action !== "update" || job?.state === "updating" || job?.state === "waiting") continue;
yield* request(item);
}
});
const cancel = Effect.fn("Upkeep.cancel")(function* (item: UpdateItem) {
if (state.jobs[item.id]?.state !== "updating") delete state.jobs[item.id];
redraw();
});
const skip = Effect.fn("Upkeep.skip")(function* (item: UpdateItem) {
state.dismissals = { ...state.dismissals, skipped: { ...state.dismissals.skipped, [item.id]: item.to } };
delete state.jobs[item.id];
redraw();
yield* save();
});
const snooze = Effect.fn("Upkeep.snooze")(function* () {
state.dismissals = { ...state.dismissals, snoozedUntil: Date.now() + SNOOZE };
state.open = false;
redraw();
yield* save();
});
const setOpen = (open: boolean) => {
state.open = open;
redraw();
};
// The list is open while the pointer is on the row or on the list, and
// closes a moment after it has left both.
let hovers = 0;
const hover = Effect.fn("Upkeep.hover")(function* (on: "row" | "list", inside: boolean) {
pointer[on] = inside;
const turn = ++hovers;
if (pointer.row || pointer.list) {
if (!state.open) setOpen(true);
return;
}
yield* Effect.sleep(HOVER_GRACE);
if (turn === hovers && state.open) setOpen(false);
});
// A chat that stopped running may free an update that waits for it.
const releaseWaiting = Effect.fn("Upkeep.releaseWaiting")(function* () {
for (const item of items()) {
if (state.jobs[item.id]?.state === "waiting" && !blocked(item, state.chats.values())) yield* start(item);
}
});
const chatChanged = Effect.fn("Upkeep.chatChanged")(function* (chat: Chat) {
state.chats.set(chat.id, chat);
yield* releaseWaiting();
});
const chatRemoved = Effect.fn("Upkeep.chatRemoved")(function* (chatId: string) {
state.chats.delete(chatId);
yield* releaseWaiting();
});
// The agents were read again: a job whose gap is gone (an update run in
// a terminal) has nothing left to show.
const agentsChanged = Effect.fn("Upkeep.agentsChanged")(function* () {
yield* loadAgents();
const behind = new Set(items().map((item) => item.id));
for (const id of Object.keys(state.jobs)) if (!behind.has(id)) delete state.jobs[id];
redraw();
});
return {
state,
views,
shown,
load,
loadUpdates,
request,
requestAll,
cancel,
skip,
snooze,
setOpen,
hover,
chatChanged,
chatRemoved,
agentsChanged,
};
});
export type Upkeep = Effect.Success<ReturnType<typeof makeUpkeep>>;Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.8latest | Nov 21, 2026 | >=5 <6 | 68.5 KB | 7 permissions | Listed |
| 0.2.7 | Nov 18, 2026 | >=5 <6 | 68 KB | 7 permissions | Listed |
| 0.2.6 | Nov 16, 2026 | >=5 <6 | 66.3 KB | 7 permissions | Listed |
| 0.2.5 | Nov 11, 2026 | >=5 <6 | 63.6 KB | 7 permissions | Listed |
| 0.2.4 | Nov 9, 2026 | >=5 <6 | 61.6 KB | 7 permissions | Listed |
| 0.2.3 | Oct 27, 2026 | >=2 <4 | 46.8 KB | 7 permissions | Listed |
No comments yet.