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

Permissions in 0.2.4

  • 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

onboarding.ts16.8 KB
// First-run setup belongs to a plugin too. Its private storage keeps progress
// across restarts; established workspaces are never interrupted by a new tour.
// Every choice here is a real setting that takes effect at once: agents,
// project folders, plugins, the theme. What waits for Start is only what
// opens chats: the first chat, and the plugin changes saved for an agent.
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as z from "zod";
import { App, Host, Kernel, KernelCallFailed, Notify, Plugin } from "divergence/effect";
import type { Chat, PluginSummary, Settings, ViewHandle, Workspace } from "divergence";
import type { AgentEntry } from "./controller.ts";
import { ChatImport } from "./chat-import.ts";

export const STEPS = ["Welcome", "Agents", "Projects", "Your app", "Visuals", "Start"] as const;
export const LAST_STEP = STEPS.length - 1;
// The official plugins the guide lets the user switch, in the order shown.
export const OPTIONAL_PLUGINS = [
  { name: "files", title: "Files", detail: "The file tree of the open folder" },
  { name: "git", title: "Git", detail: "Changes, diffs and commits" },
  { name: "terminal", title: "Terminal", detail: "A shell in the open folder" },
  { name: "market", title: "Marketplace", detail: "Plugins other people made" },
] as const;
// The stock theme families: each has a light and a dark preset
// (`<id>-light`, `<id>-dark`), which the themes plugin's `active` setting names.
export const THEMES = [
  { id: "divergence", name: "Divergence" },
  { id: "vscode", name: "VS Code Modern" },
  { id: "high-contrast", name: "High Contrast" },
  { id: "compact", name: "Compact" },
] as const;
export const VISUALS = ["chart", "diagram", "table"] as const;
export type Visual = (typeof VISUALS)[number];

export const Progress = z.object({
  done: z.boolean(),
  step: z.number().int().min(0).max(LAST_STEP),
  workspaceId: z.string().nullable(),
  firstAgent: z.string().nullable().default(null),
  saved: z.array(z.string()).default([]),
});
const KEY = "onboarding";
const ActiveTheme = z.object({ dark: z.string() });

const isReady = (agent: AgentEntry) => agent.enabled && agent.status?.state === "ready";
const message = (error: unknown) =>
  typeof error === "object" && error !== null && "message" in error ? String(error.message) : String(error);

const initialState = () => ({
  done: false,
  step: 0,
  workspaceId: null as string | null,
  firstAgent: null as string | null,
  saved: [] as string[],
  active: false,
  ready: false,
  pending: null as string | null,
  error: null as string | null,
  settings: null as Settings | null,
  agents: [] as readonly AgentEntry[],
  workspaces: [] as readonly Workspace[],
  plugins: [] as readonly PluginSummary[],
  showRegistry: false,
  theme: "divergence" as string,
  // The first agent's model and permission mode, as its composer would show them.
  firstLook: null as { agentId: string; model: string | null; mode: string | null } | null,
  change: "",
  visual: "chart" as Visual,
});
type State = ReturnType<typeof initialState>;

interface Deps {
  readonly host: Host["Service"];
  readonly app: App["Service"];
  readonly kernel: Kernel["Service"];
  readonly plugin: Plugin["Service"];
  readonly notify: Notify["Service"];
  readonly imports: ChatImport["Service"];
  readonly state: State;
  readonly views: ViewHandle[];
}

// What every action shares: drawing, saving progress, one action at a time,
// and the lists the steps read.
function makeBase({ host, state, views }: Deps) {
  const redraw = () => {
    for (const view of views) view.update();
  };
  const save = (done = state.done) =>
    host.call("host/storage.set", {
      key: KEY,
      value: { done, step: state.step, workspaceId: state.workspaceId, firstAgent: state.firstAgent, saved: state.saved },
    });
  const run = <A, E extends { readonly message: string }, R>(name: string, action: Effect.Effect<A, E, R>) =>
    Effect.suspend(() => {
      if (state.pending) return Effect.void;
      state.pending = name;
      state.error = null;
      redraw();
      return action.pipe(
        Effect.catch((error) =>
          Effect.sync(() => {
            state.error = error.message;
          }),
        ),
        Effect.ensuring(
          Effect.sync(() => {
            state.pending = null;
            redraw();
          }),
        ),
        Effect.asVoid,
      );
    });
  const projects = () => state.workspaces.filter((w) => !w.mark);
  const pluginsWorkspace = () => state.workspaces.find((w) => w.mark === "divergence") ?? null;
  const readyAgents = () => state.agents.filter(isReady);
  return { redraw, save, run, projects, pluginsWorkspace, readyAgents };
}
type Base = ReturnType<typeof makeBase>;

function makeLoading({ host, state }: Deps, { redraw, projects, pluginsWorkspace, readyAgents }: Base) {
  const loadTheme = Effect.fn("Onboarding.loadTheme")(function* () {
    const section = yield* host.call("host/plugins.settings", { name: "themes" });
    const active = ActiveTheme.safeParse(section.properties.find((p) => p.key === "active")?.value);
    const family = active.success ? active.data.dark.replace(/-dark$/, "") : "divergence";
    state.theme = THEMES.some((t) => t.id === family) ? family : "divergence";
  });
  const loadFirstLook = Effect.fn("Onboarding.loadFirstLook")(function* () {
    const agentId = state.firstAgent;
    const workspaceId = state.workspaceId ?? pluginsWorkspace()?.id;
    if (!agentId || !workspaceId) return;
    if (state.firstLook?.agentId === agentId) return;
    const { options } = yield* host.call("host/agents.options", { agentId, workspaceId });
    const label = (category: string) => {
      const option = options.find((o) => o.category === category);
      return option?.choices?.find((c) => c.value === option.value)?.name ?? null;
    };
    state.firstLook = { agentId, model: label("model"), mode: label("approval") };
  });
  const refresh = Effect.fn("Onboarding.refresh")(function* () {
    const [settings, agents, workspaces, plugins] = yield* Effect.all(
      [
        host.call("host/settings.get", {}),
        host.call("host/agents.all", {}),
        host.call("host/workspaces.list", {}),
        host.call("host/plugins.list", {}),
      ],
      { concurrency: "unbounded" },
    );
    state.settings = settings;
    state.agents = agents.agents;
    state.workspaces = workspaces.workspaces;
    state.plugins = plugins.plugins;
    // The first chat opens in the first project folder, else in the Plugins workspace.
    if (!state.workspaces.some((w) => w.id === state.workspaceId)) state.workspaceId = projects()[0]?.id ?? null;
    if (!readyAgents().some((a) => a.id === state.firstAgent)) state.firstAgent = readyAgents()[0]?.id ?? null;
    // A themes plugin without settings (an older one) keeps the default.
    yield* loadTheme().pipe(Effect.catch(() => Effect.void));
    // The preview shows the first agent's own model and mode; without them it shows the name alone.
    yield* loadFirstLook().pipe(Effect.catch(() => Effect.void));
    state.ready = true;
    redraw();
  });
  return { refresh, loadFirstLook };
}
type Loading = ReturnType<typeof makeLoading>;

// The Agents and Projects steps: agents on and signed in, folders added.
function makeSetup({ host, plugin, imports, state }: Deps, { run, save, projects }: Base, { refresh }: Loading) {
  const chooseWorkspace = (workspaceId: string) =>
    run(
      "workspace",
      Effect.gen(function* () {
        state.workspaceId = workspaceId;
        yield* save();
      }),
    );
  const addWorkspace = () =>
    run(
      "folder",
      Effect.gen(function* () {
        const { path } = yield* Effect.tryPromise({
          try: () => plugin.api.pickFolder(),
          catch: (error) => new KernelCallFailed({ method: "pickFolder", message: String(error) }),
        });
        if (!path) return;
        const workspace = yield* host.call("host/workspaces.add", { path });
        if (!projects().length) state.workspaceId = workspace.id;
        yield* save();
        yield* refresh();
        yield* imports.refresh();
      }),
    );
  // Takes the folder out of Divergence; its files stay where they are.
  const removeWorkspace = (workspaceId: string) =>
    run(
      "folder",
      Effect.gen(function* () {
        yield* host.call("host/workspaces.remove", { workspaceId });
        if (state.workspaceId === workspaceId) state.workspaceId = null;
        yield* refresh();
        yield* save();
      }),
    );
  const agentCall = (name: string, call: Effect.Effect<unknown, { readonly message: string }>) =>
    run(
      name,
      Effect.gen(function* () {
        yield* call;
        yield* refresh();
      }),
    );
  return {
    chooseWorkspace,
    addWorkspace,
    removeWorkspace,
    setAgentEnabled: (agent: AgentEntry, enabled: boolean) =>
      agentCall(`agent:${agent.id}`, host.call("host/agents.set_enabled", { agentId: agent.id, enabled })),
    signIn: (agent: AgentEntry, method: { readonly id: string }) =>
      agentCall(`auth:${agent.id}`, host.call("host/agents.authenticate", { agentId: agent.id, method: method.id })),
    updateAgent: (agent: AgentEntry) => agentCall(`update:${agent.id}`, host.call("host/agents.update", { agentId: agent.id })),
  };
}

// The Your app step: plugins on and off, the theme, and changes saved for an agent.
function makeAppChoices({ host, kernel, state }: Deps, { run, save, redraw }: Base, { refresh }: Loading) {
  const setPluginEnabled = (name: string, enabled: boolean) =>
    run(
      `plugin:${name}`,
      Effect.gen(function* () {
        yield* host
          .call("host/plugins.set_enabled", { name, enabled })
          .pipe(Effect.catchTag("NeedsReview", () => host.call("host/plugins.request_enable", { name })));
        yield* refresh();
      }),
    );
  const setTheme = (family: string) =>
    run(
      "theme",
      Effect.gen(function* () {
        yield* host.call("host/plugins.set_setting", {
          name: "themes",
          key: "active",
          value: { light: `${family}-light`, dark: `${family}-dark` },
        });
        state.theme = family;
      }),
    );
  const changeAppearance = (appearance: Settings["appearance"]) =>
    run(
      "appearance",
      Effect.gen(function* () {
        state.settings = yield* host.call("host/settings.update", { appearance });
        yield* kernel.call("theme", { mode: appearance === "system" ? undefined : appearance });
      }),
    );
  const saveChange = () =>
    Effect.gen(function* () {
      const text = state.change.trim();
      if (!text) return;
      if (!state.saved.includes(text)) state.saved = [...state.saved, text];
      state.change = "";
      yield* save();
      redraw();
    });
  const removeChange = (text: string) =>
    Effect.gen(function* () {
      state.saved = state.saved.filter((t) => t !== text);
      yield* save();
      redraw();
    });
  return { setPluginEnabled, setTheme, changeAppearance, saveChange, removeChange };
}

// Start: the saved changes become drafts in the Plugins workspace, and the
// first chat opens where the guide said it would.
function makeFinish({ host, app, notify, state }: Deps, { run, save, readyAgents, pluginsWorkspace }: Base) {
  // A saved change becomes a chat in Plugins with the change in its prompt
  // box, waiting for the user to send it.
  const draftChange = Effect.fn("Onboarding.draftChange")(function* (
    workspaceId: string,
    agentId: string,
    text: string,
    inUse: readonly string[],
  ) {
    const chat = yield* host.call("host/chats.create", { workspaceId, agentId, title: text, inUse: [...inUse] });
    const draft = yield* host.call("host/drafts.get", { chatId: chat.id });
    yield* host.call("host/drafts.update", { chatId: chat.id, revision: draft.revision, blocks: [{ type: "text", text }] });
    return chat.id;
  });
  // What an attempt already made: when saving done fails, Start again
  // reuses these instead of making a second first chat and second drafts.
  const drafts = new Map<string, string>();
  let first: Chat | null = null;
  return () =>
    run(
      "finish",
      Effect.gen(function* () {
        const agentId = readyAgents().some((a) => a.id === state.firstAgent) ? state.firstAgent : null;
        const plugins = pluginsWorkspace();
        if (agentId && plugins) {
          for (const text of state.saved.filter((t) => !drafts.has(t))) {
            const drafted = yield* draftChange(plugins.id, agentId, text, [...drafts.values()]).pipe(Effect.result);
            if (drafted._tag === "Success") drafts.set(text, drafted.success);
            else yield* notify.error(`Could not keep “${text}” as a draft: ${message(drafted.failure)}`);
          }
        }
        const workspaceId = state.workspaceId ?? plugins?.id ?? null;
        first ??= agentId && workspaceId ? yield* host.call("host/chats.create", { workspaceId, agentId, inUse: [...drafts.values()] }) : null;
        const chat = first;
        state.saved = [];
        yield* save(true);
        state.done = true;
        drafts.clear();
        first = null;
        if (chat)
          yield* app.update({ route: "chat", workspaceId: chat.workspaceId, chatId: chat.id, shared: { selectedChat: chat } });
        else yield* app.route("chat");
      }),
    );
}

// Where the guide is: opening it, resuming it, and moving between steps.
function makeFlow({ host, app, imports, state }: Deps, { run, save, redraw }: Base, { refresh, loadFirstLook }: Loading) {
  const enter = () =>
    run(
      "load",
      Effect.gen(function* () {
        state.active = true;
        if (state.done) state.step = 0;
        yield* refresh();
      }),
    );
  const initialize = Effect.fn("Onboarding.initialize")(function* () {
    const stored = yield* host.call("host/storage.get", { key: KEY });
    const parsed = Progress.safeParse(stored.value);
    if (parsed.success) {
      Object.assign(state, parsed.data);
      if (state.done) return;
    } else {
      const [workspaces, chats] = yield* Effect.all(
        [host.call("host/workspaces.list", {}), host.call("host/chats.list", {})],
        { concurrency: "unbounded" },
      );
      if (chats.chats.length || workspaces.workspaces.some((w) => !w.mark)) {
        yield* save(true);
        state.done = true;
        return;
      }
      yield* save();
    }
    // Do not steal navigation if the user opened another page while loading.
    const current = yield* app.state;
    redraw();
    if (current.route && current.route !== "chat") return;
    yield* app.route("onboarding");
    yield* enter();
  });
  const restart = () =>
    run(
      "load",
      Effect.gen(function* () {
        state.step = 0;
        state.done = false;
        state.active = true;
        yield* save();
        yield* app.route("onboarding");
        yield* refresh();
      }),
    );
  const move = (step: number) =>
    run(
      "step",
      Effect.gen(function* () {
        if (state.step === 2 && step > 2) yield* imports.refresh();
        state.step = step;
        yield* save();
      }),
    );
  // A field and a choice the guide keeps without a host call.
  const set = <K extends "change" | "visual" | "firstAgent" | "showRegistry">(key: K, value: State[K]) =>
    Effect.gen(function* () {
      state[key] = value;
      if (key === "firstAgent") {
        yield* save();
        yield* loadFirstLook().pipe(Effect.catch(() => Effect.void));
      }
      redraw();
    });
  return { initialize, enter, restart, move, set };
}

const makeOnboarding = Effect.fn("Onboarding.make")(function* () {
  const deps: Deps = {
    host: yield* Host,
    app: yield* App,
    kernel: yield* Kernel,
    plugin: yield* Plugin,
    notify: yield* Notify,
    imports: yield* ChatImport,
    state: initialState(),
    views: [],
  };
  const { state, notify } = deps;
  const base = makeBase(deps);
  const loading = makeLoading(deps, base);
  const flow = makeFlow(deps, base, loading);
  return {
    state,
    views: deps.views,
    redraw: base.redraw,
    imports: deps.imports,
    projects: base.projects,
    pluginsWorkspace: base.pluginsWorkspace,
    readyAgents: base.readyAgents,
    ...flow,
    initialize: () =>
      flow.initialize().pipe(Effect.catch((error) => notify.error(`Could not load onboarding: ${error.message}`))),
    ...makeSetup(deps, base, loading),
    ...makeAppChoices(deps, base, loading),
    finish: makeFinish(deps, base),
    retry: () => base.run("load", loading.refresh()),
    refresh: () =>
      state.active
        ? loading.refresh().pipe(
            Effect.catch((error) =>
              Effect.sync(() => {
                state.error = error.message;
                base.redraw();
              }),
            ),
          )
        : Effect.void,
  };
});

export class Onboarding extends Context.Service<Onboarding, Effect.Success<ReturnType<typeof makeOnboarding>>>()(
  "settings/Onboarding",
) {
  static readonly layer = Layer.effect(Onboarding, makeOnboarding());
}

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.