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

views/plugins.tsx10.3 KB
// The Plugins section: one row per plugin with its state, badges, grants
// and the review card that only the native enable flow can open.
// HTM whitespace is significant; keep these templates out of Prettier's HTML formatter.
import type { EffectViewContext } from "divergence/effect";
import type { PermissionEntry, PluginSummary, Risk } from "divergence";
import { PERMISSIONS, RISK_NAMES } from "../model.ts";
import type { SettingsPage } from "../controller.ts";
import { DOT, TITLE_LINE, besideTitle, card, listRow, section, setting, column, fill, row } from "./layout.tsx";

// The risk dot: muted for low, softened warning for medium, warning for
// high, danger for dangerous and unsafe.
const RISK_TONES: Record<Risk, { tone: "muted" | "warning" | "danger"; opacity?: number }> = {
  always: { tone: "muted" },
  low: { tone: "muted" },
  medium: { tone: "warning", opacity: 0.75 },
  high: { tone: "warning" },
  dangerous: { tone: "danger" },
  unsafe: { tone: "danger" },
  reserved: { tone: "muted" },
};

function pluginBadges(plugin: PluginSummary) {
  return [
    // Official is the ordinary case in this list; only the exceptions get
    // a badge (the review card still names it).
    plugin.claimsOfficial ? <badge variant="warning">Claims an official id</badge> : null,
    !plugin.official && plugin.source === "local" ? <badge>Local</badge> : null,
    plugin.source === "marketplace" ? <badge>Marketplace</badge> : null,
    plugin.basedOn ? <badge>{`Mod of ${plugin.basedOn.id}@${plugin.basedOn.version}`}</badge> : null,
    // No OS sandbox holds its code on this system (Windows for now):
    // only the permission checks do. Its enable card is held for 2 s.
    !plugin.official && plugin.sandboxed === false ? <badge variant="danger">Sandbox not available</badge> : null,
    // The OS sandbox holds part of what its grants ask (`enforcement`,
    // from the runtime's launcher): the rows below say what it does not.
    plugin.sandboxed !== false && enforcementOf(plugin)?.level === "partial"
      ? <badge variant="warning">Partly sandboxed</badge>
      : null,
  ];
}

type Enforcement = {
  level: "sandboxed" | "partial" | "unsandboxed";
  mechanism: string;
  unenforced?: { area: string; detail: string }[];
  reason?: string;
};

// What the OS sandbox holds for the plugin's runtime: a field this view's
// generated summary type does not have yet.
function enforcementOf(plugin: PluginSummary): Enforcement | undefined {
  return (plugin as PluginSummary & { enforcement?: Enforcement }).enforcement;
}

// The sandbox status under a plugin's grants: what holds, and each
// restriction it asks for that the OS does not enforce here.
function sandboxRows(plugin: PluginSummary) {
  const enforcement = enforcementOf(plugin);
  if (!enforcement) return null;
  const summary =
    enforcement.level === "sandboxed"
      ? `Sandboxed (${enforcement.mechanism}): every native restriction its grants ask for holds.`
      : enforcement.level === "partial"
        ? `Partly sandboxed (${enforcement.mechanism}): what does not hold is listed.`
        : `Not sandboxed: ${enforcement.reason ?? "this system has no plugin sandbox"}. Native file, network and program access is not restricted.`;
  return (
    <div {...column} gap="small" padding="small">
      <text style="body" size="xs" tone={enforcement.level === "sandboxed" ? "muted" : enforcement.level === "partial" ? "warning" : "danger"}>{summary}</text>
      {(enforcement.unenforced ?? []).map(
                (item) => <text style="body" size="xs" tone="muted">{`${item.area}: ${item.detail}`}</text>,
              )}
    </div>
  );
}

// Failed and waiting states are badges; the quiet ones are a word.
function pluginState(plugin: PluginSummary) {
  // `waiting` arrived after the generated type was written; compare the
  // widened state so the badge survives without a cast.
  const state: string = plugin.state;
  if (state === "failed") return <badge variant="danger">Failed</badge>;
  if (state === "waiting") return <badge variant="warning">Waiting</badge>;
  if (plugin.enabled && plugin.pending.length) return <badge variant="warning">Needs review</badge>;
  if (state === "reload_pending") return <badge variant="warning">Reload pending</badge>;
  // On or off is the switch's to say; only a plugin that has none yet (it
  // is enabled from its review card) says it in words.
  return plugin.enabled || state === "disabled"
    ? null
    : <text style="body" size="xs" tone="faint">Not enabled</text>;
}

function grantRow(
  ctx: EffectViewContext<object>,
  actions: SettingsPage["Service"],
  plugin: PluginSummary,
  entry: PermissionEntry,
) {
  // A permission only official plugins can have is never granted to
  // another; it shows faint, with the reason why.
  const blocked = entry.risk === "reserved" && !plugin.official;
  const risk = { ...RISK_TONES[entry.risk], label: RISK_NAMES[entry.risk] };
  const label = PERMISSIONS[entry.permission].label;
  const revocable = entry.granted && !plugin.official && entry.risk !== "always";
  return (
    <div {...row} gap="small" padding="small" paddingY="small" alignItems="start">
      <div {...column} gap="small" padding="small" paddingY={6}>
          <div {...column} gap="small" padding="small" width={7} flexShrink={0} height={7} opacity={risk.opacity} background={DOT[risk.tone]} borderRadius="full" />
        </div>
      <div {...column} {...fill} padding="small">
          <div {...row} gap="small" padding="small" flexWrap="wrap">
              <text style="body" size="sm" weight={560} tone={blocked ? "faint" : "foreground"}>{label}</text>
              {entry.scope ? <text style="mono" size="xs" tone={blocked ? "faint" : "muted"}>{entry.scope}</text> : null}
            </div>
          <text style="body" size="xs" tone="muted">{blocked ? "Only official plugins can have this" : (entry.reason ?? "")}</text>
        </div>
      <text style="body" size="xs" tone={blocked || !entry.granted ? "faint" : risk.tone}>{blocked ? "Refused" : entry.granted ? risk.label : "Not granted"}</text>
      {revocable
                  ? <button id={`revoke-${plugin.name}-${entry.permission}-${entry.scope ?? ""}`} label="Revoke" variant="ghost" small onClick={() => ctx.run(actions.revoke(plugin.name, entry))} />
                  : null}
    </div>
  );
}

function pluginRow(ctx: EffectViewContext<object>, actions: SettingsPage["Service"], plugin: PluginSummary) {
  const state = actions.state;
  const open = !!state.openPermissions[plugin.name];
  // A plugin never enabled, or turned off with something new to review,
  // is enabled from its card. A switch is for the rest.
  const reviewFirst = !plugin.enabled && (plugin.state === "not_enabled" || plugin.pending.length > 0);
  const togglePermissions = () => {
    state.openPermissions = { ...state.openPermissions, [plugin.name]: !open };
    ctx.update();
  };
  const reviewButtons = [
    reviewFirst
      ? <button id={`review-${plugin.name}`} label="Review and enable…" small variant="primary" onClick={() => ctx.run(actions.review(plugin.name))} />
      : null,
    plugin.enabled && plugin.pending.length
      ? <button id={`review-${plugin.name}`} label="Review permissions…" small variant="primary" onClick={() => ctx.run(actions.review(plugin.name))} />
      : null,
  ].filter(Boolean);
  // An official plugin's id is `divergence/<name>`; any other id is worth
  // reading, so it follows the version.
  const ownId = plugin.official && plugin.id === `divergence/${plugin.name}`;
  // Two lines: what it is and its controls, then what it does. Permissions
  // and reload are icon buttons on the title line; the permission list
  // opens under the description.
  return listRow(
    besideTitle(
      reviewFirst
        ? null
        : <switch id={`plugin-${plugin.name}`} label="" checked={plugin.enabled} onChange={(e: { value: boolean }) => ctx.run(actions.setPluginEnabled(plugin.name, e.value))} />,
      36,
    ),
    (
      <div {...column} {...fill} gap={2}>
        <div {...row} gap="small" height={TITLE_LINE}>
              <text style="body" size="sm" bold>{plugin.name}</text>
              <text style="body" size="xs" tone="faint">{plugin.version}</text>
              {ownId ? null : <text style="mono" size="xs" tone="faint">{plugin.id}</text>}
              {pluginBadges(plugin)}
              <spacer />
              {pluginState(plugin)}
            </div>
        {plugin.description ? <text style="body" size="xs" tone="muted">{plugin.description}</text> : null}
        {plugin.error ? <code>{plugin.error}</code> : null}
        {reviewButtons.length ? <div {...row} gap="small" paddingY={4}>{reviewButtons}</div> : null}
        {open
                      ? (
                        <panel marginTop={6}>
                          {plugin.permissions.map((entry) => grantRow(ctx, actions, plugin, entry))}
                          {sandboxRows(plugin)}
                        </panel>
                      )
                      : null}
      </div>
    ),
    besideTitle(
      (
        <div {...row} gap={2}>
          {plugin.permissions.length
                        ? <button id={`permissions-${plugin.name}`} icon="shield-check" variant="ghost" small active={open} tooltip={open ? "Hide permissions" : `Permissions (${plugin.permissions.filter((entry) => entry.granted).length} of ${plugin.permissions.length} granted)`} onClick={togglePermissions} />
                        : null}
          <button id={`reload-${plugin.name}`} icon="rotate-cw" variant="ghost" small tooltip="Reload" onClick={() => ctx.run(actions.reload(plugin.name))} />
        </div>
      ),
    ),
  );
}

export function renderPlugins(ctx: EffectViewContext<object>, actions: SettingsPage["Service"]) {
  const p = actions.state.data.plugins;
  if (!p) return <empty>Loading…</empty>;
  const providesAgents = (plugin: PluginSummary) =>
    plugin.permissions.some((entry) => entry.permission === "agents.provide");
  const services = p.filter(providesAgents);
  const others = p.filter((plugin) => !providesAgents(plugin));
  return (
    <div {...column} gap="large" padding="small">
      {section("Interface", "Plugins live in the Plugins workspace. Edit them there; they reload on save. A new plugin runs only once you enable it here.", card(others.map((plugin) => pluginRow(ctx, actions, plugin))))}
      {services.length ? section("Agents", "Each brings the agents it names.", card(services.map((plugin) => pluginRow(ctx, actions, plugin)))) : null}
    </div>
  );
}

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.