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

Permissions in 0.2.5

  • Manage plugins plugins.manageOfficial onlyReloads and enables plugins. Only official plugins can have it.List, enable, disable and reload plugins, install updates, and quit to finish an update
  • Change app settings settings.writeHighChanges the app settings.Change the settings and the theme
  • Manage agents agents.manageHighEnables, disables and signs in agents, and changes their settings.Turn agents on and off, sign in to them and update them
  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Import an agent's own sessions as chats, add project folders, and open the first chat and the changes saved in the first-run guide
  • Read chats chats.readMediumReads your transcripts and chat lists.List the workspaces an agent's sessions can be imported into, and hold an agent's update until its chats stop running
  • Read app settings settings.readLowReads the app settings.Show the settings, and the tools and rules of every plugin
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw settings, its list of sections in the sidebar's place, and the first-run guideSlots: centerleft

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 Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
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";
/// The host's busy mark while the downloaded app waits for every chat to
/// be idle before it answers `restart`.
export const RESTARTING = "restarting when every chat is idle";
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;
}

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());
  // The list closes with its last item, so the next one does not open it.
  const redraw = () => {
    if (state.open && !shown().length) state.open = 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", {});
      // The host answers once every chat is idle, and no run starts after.
      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();
    // A job queued behind another install looks at the runs again when its
    // turn comes (`undefined`): a chat may have started while it queued.
    const done = yield* installer
      .withPermits(1)(Effect.suspend(() => (blocked(item, state.chats.values()) ? Effect.succeed(undefined) : 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 if (done.success === undefined) {
      state.jobs[item.id] = { state: "waiting" };
    } 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();
  };

  // 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,
    chatChanged,
    chatRemoved,
    agentsChanged,
  };
});

/// One owner of every update, so the row and Settings > Updates share its
/// jobs, its wait for runs and its single installer.
export class Upkeep extends Context.Service<Upkeep, Effect.Success<ReturnType<typeof makeUpkeep>>>()("settings/Upkeep") {
  static readonly layer = Layer.effect(Upkeep, makeUpkeep());
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.8latestNov 21, 2026>=5 <668.5 KB7 permissionsListed
0.2.7Nov 18, 2026>=5 <668 KB7 permissionsListed
0.2.6Nov 16, 2026>=5 <666.3 KB7 permissionsListed
0.2.5Nov 11, 2026>=5 <663.6 KB7 permissionsListed
0.2.4Nov 9, 2026>=5 <661.6 KB7 permissionsListed
0.2.3Oct 27, 2026>=2 <446.8 KB7 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.