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
controller.ts18.1 KB
// The settings page's state and its effects: loading the page, changing a
// setting, enabling a plugin or agent, recording a key. Views only mutate
// this state and redraw; every host or kernel call goes through here.
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import { App, Host, Kernel, Notify, Plugin } from "divergence/effect";
import type { KernelCallFailed, HostError, PermissionNotGranted } from "divergence/effect";
import type {
AgentInfo,
CommandInfo,
PluginSettingProperty,
PluginSummary,
PresetColor,
SettingValue,
Settings,
ToolsOverview,
UpdateStatus,
ViewHandle,
Workspace,
} from "divergence";
import { chordOf } from "./model.ts";
import type { SectionData } from "./model.ts";
import { Upkeep, updateItems } from "./upkeep.ts";
import { ArchivedChats } from "./archived.ts";
export type AgentEntry = AgentInfo & { readonly enabled: boolean };
export type PageError = HostError | KernelCallFailed | PermissionNotGranted;
// Every tag a host or kernel call fails with on this page.
const ERROR_TAGS = ["PermissionNotGranted", "NeedsReview", "HostCallFailed", "KernelCallFailed"] as const;
/// One key being recorded, with the strokes so far as the kernel named
/// them and as a keyboard shows them.
interface Recording {
command: string;
strokes: { readonly key: string; readonly label: string }[];
waiting: boolean;
}
type PageData =
| { readonly status: "pending"; readonly settings: null; readonly plugins: null }
| { readonly status: "failed"; readonly settings: null; readonly plugins: null; readonly error: string }
| { readonly status: "ready"; readonly settings: Settings; readonly plugins: readonly PluginSummary[] };
export interface PageState {
section: string;
updates: UpdateStatus | null;
data: PageData;
agents: readonly AgentEntry[];
keys: { readonly commands: readonly CommandInfo[]; readonly errors: readonly string[] } | null;
workspaces: readonly Workspace[];
/// The preset colours a workspace's folder can take.
colors: readonly PresetColor[];
/** `undefined` until the Tools section is first opened; `null` in a build without plugin tools. */
tools: ToolsOverview | null | undefined;
keysQuery: string;
recording: Recording | null;
sections: Record<string, SectionData>;
drafts: Record<string, string>;
draftErrors: Record<string, string>;
sectionViews: Record<string, number | null>;
showRegistry: boolean;
openPermissions: Record<string, boolean>;
/// The sign-in under way, `auth:<id>`: the agent rows wait while it runs.
pending: string | null;
}
export function initialState(): PageState {
return {
section: "general",
updates: null,
data: { status: "pending", settings: null, plugins: null },
agents: [],
keys: null,
workspaces: [],
colors: [],
tools: undefined,
keysQuery: "",
recording: null,
sections: {},
drafts: {},
draftErrors: {},
sectionViews: {},
showRegistry: false,
openPermissions: {},
pending: null,
};
}
const makePage = Effect.fn("SettingsPage.make")(function* () {
const host = yield* Host;
const kernel = yield* Kernel;
const app = yield* App;
const notify = yield* Notify;
const plugin = yield* Plugin;
const upkeep = yield* Upkeep;
const archived = yield* ArchivedChats;
const state = initialState();
const views: ViewHandle[] = [];
const redraw = () => {
for (const view of views) view.update();
};
// `run(label, action)` from the original: the label and the error's
// message go to a notice, whatever went wrong.
const attempt = <A, R>(label: string, effect: Effect.Effect<A, PageError, R>) =>
effect.pipe(
Effect.catchTag(ERROR_TAGS, (error) => notify.error(`${label}: ${error.message}`)),
Effect.asVoid,
);
// The plugin whose section is open, if one is.
const sectionPlugin = () => (state.section.startsWith("plugin:") ? state.section.slice("plugin:".length) : null);
const loadKeys = Effect.fn("SettingsPage.loadKeys")(function* () {
state.keys = yield* kernel.call("commands", {});
redraw();
});
// Only while the Tools section is open: listing the tools starts every
// plugin that gives them, which otherwise waits until a session needs it.
// Through `call`: a build without plugin tools answers "unknown host method".
const loadTools = Effect.fn("SettingsPage.loadTools")(function* () {
state.tools = yield* host
.call("host/tools.list", {})
.pipe(Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], () => Effect.succeed(null)));
redraw();
});
const loadSection = Effect.fn("SettingsPage.loadSection")(function* (name: string) {
state.sections[name] = yield* host
.call("host/plugins.settings", { name })
.pipe(
Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], (error) =>
Effect.succeed<SectionData>({ name, error: error.message, properties: [], notices: [] }),
),
);
const custom = yield* kernel
.call("settings_view", { plugin: name })
.pipe(Effect.catchTag(["KernelCallFailed", "PermissionNotGranted"], () => Effect.succeed({ view: null })));
state.sectionViews[name] = custom.view;
redraw();
});
const load = Effect.fn("SettingsPage.load")(function* () {
const loaded = yield* Effect.all(
[
host.call("host/settings.get", {}),
host.call("host/agents.all", {}),
host.call("host/plugins.list", {}),
kernel.call("commands", {}),
host.call("host/workspaces.list", {}),
host.call("host/updates.status", {}),
],
{ concurrency: "unbounded" },
).pipe(
// A page that never loaded says why, with Try again; one already drawn
// keeps what it shows, and the failure goes to the caller.
Effect.catchTag(ERROR_TAGS, (error) => {
if (state.data.status === "ready") return Effect.fail(error);
state.data = { status: "failed", settings: null, plugins: null, error: error.message };
return Effect.succeed(null);
}),
);
if (!loaded) return redraw();
const [settings, agents, plugins, commands, workspaces, updates] = loaded;
state.updates = updates;
state.data = { status: "ready", settings, plugins: plugins.plugins };
state.agents = agents.agents;
state.keys = commands;
state.workspaces = workspaces.workspaces;
state.colors = workspaces.colors ?? [];
if (state.section === "tools") yield* loadTools();
redraw();
// The chat plugin's section also says whether this page draws its film
// grain, so it loads with the page.
const open = sectionPlugin();
yield* Effect.forEach(new Set(["chat", open ?? "chat"]), loadSection, { concurrency: "unbounded" });
});
const updateSettings = Effect.fn("SettingsPage.updateSettings")(function* (patch: Partial<Settings>) {
const settings = yield* host.call("host/settings.update", patch);
if (state.data.status === "ready") state.data = { ...state.data, settings };
redraw();
});
const changeAppearance = Effect.fn("SettingsPage.changeAppearance")(function* (value: Settings["appearance"]) {
yield* updateSettings({ appearance: value });
yield* kernel.call("theme", { mode: value === "system" ? undefined : value });
});
// One sign-in at a time: a second press while one runs does nothing.
const signIn = (agent: AgentEntry, method: { readonly id: string }) =>
Effect.suspend(() => {
if (state.pending) return Effect.void;
state.pending = `auth:${agent.id}`;
redraw();
return host.call("host/agents.authenticate", { agentId: agent.id, method: method.id }).pipe(
// The baseline notified without a level; keep the call identical.
Effect.tap(() => Effect.sync(() => plugin.api.notify(`${agent.name}: signed in.`))),
Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], (error) =>
notify.error(`${agent.name}: ${error.message}`),
),
Effect.ensuring(
Effect.sync(() => {
state.pending = null;
redraw();
}),
),
);
});
// The switch draws the host's answer, so a refused change stays where it was.
const setAgentEnabled = (agent: AgentEntry, enabled: boolean) =>
attempt(`Could not turn ${enabled ? "on" : "off"} ${agent.name}`, host.call("host/agents.set_enabled", { agentId: agent.id, enabled }));
// Only the native card grants anything: the page asks for it, and the
// user answers there.
const review = (name: string) =>
attempt(
`Could not review ${name}`,
Effect.gen(function* () {
const { requestId } = yield* host.call("host/plugins.request_enable", { name });
if (!requestId) yield* load();
}),
);
// On again works only for a plugin enabled before with nothing new to
// review; anything else goes to its card.
const setPluginEnabled = (name: string, enabled: boolean) =>
host.call("host/plugins.set_enabled", { name, enabled }).pipe(
Effect.catchTag("NeedsReview", () => host.call("host/plugins.request_enable", { name })),
Effect.catchTag(["HostCallFailed", "PermissionNotGranted"], (error) =>
notify.error(`Could not change ${name}: ${error.message}`),
),
Effect.asVoid,
);
const revoke = (name: string, entry: PluginSummary["permissions"][number]) =>
attempt(
`Could not revoke ${entry.permission}`,
host.call("host/plugins.revoke", { name, permission: entry.permission, scope: entry.scope }),
);
const reload = (name: string) =>
attempt(
`Could not reload ${name}`,
Effect.gen(function* () {
yield* host.call("host/plugins.reload", { name });
yield* load();
}),
);
const reportBug = () => attempt("Could not open the bug report form", host.call("host/market.open_bug_form", {}));
// A workspace's mark: a folder in `color`, or (`null`) its project
// icon. The workspace-changed event that follows reloads the page.
const setWorkspaceColor = (workspaceId: string, color: PresetColor | null) =>
attempt("Could not change the workspace's icon", host.call("host/workspaces.set_color", { workspaceId, color }));
const updateTools = Effect.fn("SettingsPage.updateTools")(function* (patch: Partial<Settings["tools"]>) {
const tools = state.data.settings?.tools ?? { mode: "code", disabled: [], disabledRules: [] };
yield* updateSettings({ tools: { ...tools, ...patch } });
state.tools = yield* host.call("host/tools.list", {});
redraw();
});
const route = (name: string) => app.route(name);
// An agent's Update, Install and restart and Update plugins are the
// update row's jobs, so they wait for the runs they would cut off and
// take turns at its one installer.
const requestUpdate = (id: string) => {
const item = updateItems(state.agents, state.updates).find((item) => item.id === id);
return item ? upkeep.request(item) : Effect.void;
};
const updateAgent = (agent: AgentEntry) => requestUpdate(agent.id);
const installApp = () => requestUpdate("app");
const applyPlugins = () => requestUpdate("plugins");
const checkNow = () => attempt("Could not check for updates", host.call("host/updates.check", {}));
const refreshUpdates = Effect.fn("SettingsPage.refreshUpdates")(function* () {
state.updates = yield* host.call("host/updates.status", {});
redraw();
});
// --- Keyboard Shortcuts ---------------------------------------------------
const keysRun = (label: string, action: Effect.Effect<unknown, PageError>) =>
attempt(label, Effect.andThen(action, loadKeys));
const record = Effect.fn("SettingsPage.record")(function* (command: CommandInfo) {
const current: Recording = (state.recording = { command: command.id, strokes: [], waiting: true });
redraw();
const result = yield* kernel
.call("keys.record", {})
.pipe(Effect.catchTag(["KernelCallFailed", "PermissionNotGranted"], (error) => Effect.succeed({ key: null, error: error.message } as const)));
// A newer recording, even of the same command, answered this call with no key.
if (state.recording !== current) return;
current.waiting = false;
if (result.key) current.strokes.push({ key: result.key, label: result.label });
else if ("error" in result && result.error) yield* notify.warning(`That key cannot be bound: ${result.error}`);
if (!current.strokes.length) state.recording = null;
redraw();
});
const recordMore = Effect.fn("SettingsPage.recordMore")(function* () {
const current = state.recording;
if (!current || current.strokes.length >= 2) return;
current.waiting = true;
redraw();
const result = yield* kernel
.call("keys.record", {})
.pipe(Effect.catchTag(["KernelCallFailed", "PermissionNotGranted"], () => Effect.succeed({ key: null } as const)));
if (state.recording !== current) return;
current.waiting = false;
if (result.key) current.strokes.push({ key: result.key, label: result.label });
redraw();
});
const cancelRecord = kernel.call("keys.record_cancel", {}).pipe(
Effect.catchTag(["KernelCallFailed", "PermissionNotGranted"], () => Effect.void),
Effect.asVoid,
);
// View-side: clears the recorder at once; the cancel goes out on its own.
const stopRecording = () => {
const waiting = state.recording?.waiting ?? false;
state.recording = null;
redraw();
return waiting;
};
const saveRecording = Effect.fn("SettingsPage.saveRecording")(function* () {
const current = state.recording;
state.recording = null;
if (!current?.strokes.length) {
redraw();
return;
}
yield* keysRun(
"Could not change the key",
kernel.call("keybindings.change", { command: current.command, change: "set", key: chordOf(current.strokes.map((s) => s.key)) }),
);
});
const openKeybindings = () => attempt("Could not open keybindings.json", kernel.call("keybindings.open", {}));
const resetKey = (command: CommandInfo) =>
keysRun("Could not reset the key", kernel.call("keybindings.change", { command: command.id, change: "reset" }));
const unbindKey = (command: CommandInfo) =>
keysRun("Could not remove the key", kernel.call("keybindings.change", { command: command.id, change: "unbind" }));
// --- a plugin's own section -----------------------------------------------
const saveSetting = Effect.fn("SettingsPage.saveSetting")(function* (
name: string,
property: PluginSettingProperty,
value: SettingValue,
) {
const k = `${name}/${property.key}`;
yield* host.call("host/plugins.set_setting", { name, key: property.key, value }).pipe(
Effect.tap((result) =>
Effect.andThen(
Effect.sync(() => {
delete state.drafts[k];
delete state.draftErrors[k];
}),
result.requestId
? // The baseline notified without a level; keep the call identical.
Effect.sync(() => plugin.api.notify(`${property.title}: allow the change on the card to use it.`))
: Effect.void,
),
),
Effect.catchTag(["HostCallFailed", "NeedsReview", "PermissionNotGranted"], (error) =>
Effect.sync(() => {
state.draftErrors[k] = error.message;
}),
),
);
yield* loadSection(name);
});
// The masked secret field tells the page its save failed; the host
// never sees the value itself.
const secretFailed = (property: PluginSettingProperty, error: string) => notify.error(`${property.title}: ${error}`);
// Text and path settings pick what they show from a native dialog.
const pickPath = Effect.fn("SettingsPage.pickPath")(function* (property: PluginSettingProperty) {
const picked =
property.kind === "folder"
? (yield* Effect.promise(() => plugin.api.pickFolder())).path
: (yield* Effect.promise(() => plugin.api.pickImages())).paths[0];
return picked ?? null;
});
const setDraft = (key: string, value: string) => {
state.drafts[key] = value;
delete state.draftErrors[key];
redraw();
};
const openSection = Effect.fn("SettingsPage.openSection")(function* (id: string, plugin?: string) {
state.section = id;
redraw();
if (plugin) yield* loadSection(plugin);
else if (id === "keys") yield* loadKeys();
else if (id === "tools") yield* loadTools();
else if (id === "archived") yield* archived.load();
});
// A section's own command (Settings: Agents and the rest): Settings opens
// on it, from wherever the app is.
const showSection = Effect.fn("SettingsPage.showSection")(function* (id: string) {
yield* route("settings");
yield* openSection(id);
});
// The palette's Assign request for a command in conflict: Keyboard
// Shortcuts, searched for that command. The divergence/settings service
// reaches this; the route brings the page on screen.
const showShortcuts = Effect.fn("SettingsPage.showShortcuts")(function* (query: string) {
state.section = "keys";
state.keysQuery = query;
redraw();
yield* route("settings");
// The page is already on its way; a keys load that fails now is a
// notice, not a failed service call.
if (state.data.status === "ready")
yield* loadKeys().pipe(
Effect.catchTag(["KernelCallFailed", "PermissionNotGranted"], (error) =>
notify.error(`Could not load keyboard shortcuts: ${error.message}`),
),
);
return null;
});
return {
state,
views,
upkeep,
archived,
load,
loadKeys,
loadSection,
updateSettings,
changeAppearance,
signIn,
updateAgent,
setAgentEnabled,
review,
setPluginEnabled,
revoke,
reload,
reportBug,
updateTools,
setWorkspaceColor,
route,
installApp,
applyPlugins,
checkNow,
refreshUpdates,
keysRun,
record,
recordMore,
cancelRecord,
stopRecording,
saveRecording,
openKeybindings,
resetKey,
unbindKey,
saveSetting,
secretFailed,
pickPath,
setDraft,
openSection,
showSection,
showShortcuts,
sectionPlugin,
};
});
export class SettingsPage extends Context.Service<SettingsPage, Effect.Success<ReturnType<typeof makePage>>>()(
"settings/SettingsPage",
) {
static readonly layer = Layer.effect(SettingsPage, makePage());
}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.