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.8
Permissions in 0.2.8
Files
onboarding.ts17 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";
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 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, 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();
}),
);
// 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;
// Without a ready agent nothing could hold the saved changes, so
// they stay in the guide's progress for when it runs again.
const kept = agentId && plugins ? [] : state.saved;
state.saved = kept;
yield* save(true);
state.done = true;
drafts.clear();
first = null;
if (kept.length)
yield* notify.warning(
`${kept.length === 1 ? "Your saved change waits" : `Your ${kept.length} saved changes wait`} for a ready agent. Once one is ready, use Run onboarding again to start ${kept.length === 1 ? "it" : "them"}.`,
);
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, 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* () {
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,
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,
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
| 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.