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 convergence/settings@0.2.2

Permissions in 0.2.2

  • 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
  • Read chats chats.readMediumReads your transcripts and chat lists.List the workspaces an agent's sessions can be imported into
  • 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 and the return-to-onboarding buttonSlots: centertitle

Files

views/agents.ts8.8 KB
// The Agents section: every agent the host serves, with its account state,
// plan usage and one-click updates. Registry agents collapse behind one row.
// HTM whitespace is significant; keep these templates out of Prettier's HTML formatter.
import { html as htm } from "convergence";
import type * as Effect from "effect/Effect";
import type { EffectViewContext } from "convergence/effect";
import type { AgentEntry, PageError, SettingsPage } from "../controller.ts";
import { TITLE_LINE, besideTitle, card, listRow, section, setting, column, fill, row } from "./layout.ts";

type AgentActions = {
  state: { agents: readonly AgentEntry[]; showRegistry: boolean; pending?: string | null };
  setAgentEnabled(agent: AgentEntry, enabled: boolean): Effect.Effect<unknown, PageError>;
  signIn(agent: AgentEntry, method: { readonly id: string }): Effect.Effect<unknown, PageError>;
  updateAgent(agent: AgentEntry): Effect.Effect<unknown, PageError>;
};

// The host runs 20 agent processes and stops an idle one after 10 minutes when the setting is unset.
const DEFAULT_PROCESS_LIMIT = 20;
const DEFAULT_IDLE_MINUTES = 10;
// A preset picker whose current value stays listed when it is not a preset.
function presets(id: string, value: number, choices: readonly number[], label: (n: number) => string, onChange: (n: number) => void) {
  const values = choices.includes(value) ? choices : [...choices, value].sort((a, b) => a - b);
  return htm`
      <select id=${id} value=${String(value)} small
        options=${values.map((n) => ({ value: String(n), label: label(n) }))}
        onChange=${(e: { value: string }) => onChange(Number(e.value))} />`;
}

// How much of the account's plan is used, once it is worth saying.
function usageRow(a: AgentEntry) {
  const windows = a.usageLimits?.windows ?? [];
  if (!a.enabled || !windows.length) return null;
  const shown = windows.filter((w) => w.usedPercent >= 1 || w.blocked);
  if (!shown.length) return null;
  return htm`
      <div ...${row} gap="medium" padding="small" flexWrap="wrap">
        ${shown.map((w) => {
          const tone = w.blocked ? "danger" : w.usedPercent >= 90 ? "warning" : "muted";
          const resets = w.resetsAt
            ? ` · resets ${new Date(w.resetsAt).toLocaleString([], { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })}`
            : "";
          return htm`<text style="body" size="xs" tone=${tone}>${`${w.label} ${Math.round(w.usedPercent)}%${resets}`}</text>`;
        })}
      </div>`;
}

// The version, and a one-click upgrade only when the installer that owns
// the binary could be proven. Anything else stays manual.
function maintenanceNote(a: AgentEntry) {
  const m = a.maintenance;
  if (!a.enabled || !m) return null;
  const behind = m.latestVersion && m.latestVersion !== m.installedVersion;
  if (!behind) return null;
  const how = m.canUpdate ? "" : " Update it the way you installed it.";
  return htm`<text style="body" size="xs" tone="warning">${`${m.latestVersion} is available.${how}`}</text>`;
}

function maintenanceAction(ctx: EffectViewContext<object>, actions: AgentActions, a: AgentEntry) {
  const m = a.maintenance;
  if (!a.enabled || !m?.canUpdate) return null;
  return htm`<button id=${`update-${a.id}`} label=${`Update with ${m.manager}`} small variant="outline" disabled=${Boolean(actions.state.pending)} loading=${actions.state.pending === `update:${a.id}`} onClick=${() => ctx.run(actions.updateAgent(a))} />`;
}

function agentRow(ctx: EffectViewContext<object>, actions: AgentActions, a: AgentEntry) {
  const status = a.status?.state;
  const badge =
    status === "ready"
      ? htm`<badge variant="success">Ready</badge>`
      : status === "starting" && a.enabled
        ? htm`<badge>Checking…</badge>`
      : status === "auth_required" && a.enabled
        ? htm`<badge variant="warning">Sign in needed</badge>`
        : a.enabled
          ? htm`<badge variant="danger">Unavailable</badge>`
          : null;
  const statusMessage = a.status !== undefined && "message" in a.status ? a.status.message : null;
  const detail = status !== "ready" && a.enabled && statusMessage ? statusMessage : a.description;
  const methods = a.authMethods ?? [];
  const actions$ = [
    ...(a.enabled && status !== "ready" && status !== "starting" && methods.length
      ? methods.map(
          (m) =>
            htm`<button id=${`auth-${a.id}-${m.id}`} label=${m.name} small variant="primary" disabled=${Boolean(actions.state.pending)} loading=${actions.state.pending === `auth:${a.id}`} onClick=${() => ctx.run(actions.signIn(a, m))} />`,
        )
      : []),
    maintenanceAction(ctx, actions, a),
  ].filter(Boolean);
  // One left edge under the title, the switch centred on the title line.
  return listRow(
    besideTitle(
      htm`<switch id=${`agent-${a.id}`} label="" checked=${a.enabled} disabled=${Boolean(actions.state.pending)} onChange=${(e: { value: boolean }) => ctx.run(actions.setAgentEnabled(a, e.value))} />`,
      36,
    ),
    htm`
        <div ...${column} ...${fill} gap=${4}>
          <div ...${row} gap="small" height=${TITLE_LINE}>
            <icon name="bot" small tone="muted" svg=${a.icon} />
            <text style="body" size="sm" bold>${a.name}</text>
            ${a.version ? htm`<text style="body" size="xs" tone="faint">${a.version}</text>` : null}
            <spacer />
            ${badge}
          </div>
          ${detail ? htm`<text style="body" size="xs" tone="muted">${detail}</text>` : null}
          ${usageRow(a)}
          ${maintenanceNote(a)}
          ${actions$.length ? htm`<div ...${row} gap="small" flexWrap="wrap">${actions$}</div>` : null}
        </div>`,
  );
}

export function renderAgents(ctx: EffectViewContext<object>, actions: SettingsPage["Service"]) {
  const state = actions.state;
  return htm`
      <div ...${column} gap="large" padding="small">
        ${section(
          "Processes",
          null,
          card([
            setting({
              title: "Agent processes",
              description: "Past this many running at once, the least recently used idle agent stops. A chat that is working is never stopped.",
              control: presets(
                "agent-process-limit",
                state.settings?.agentProcessLimit ?? DEFAULT_PROCESS_LIMIT,
                [5, 10, 20, 40],
                (count) => `${count} processes`,
                (value) => ctx.run(actions.updateSettings({ agentProcessLimit: value })),
              ),
            }),
            setting({
              title: "Stop idle agents after",
              description: "An idle agent stops after this time and resumes when its chat is shown or sent to.",
              control: presets(
                "agent-idle-minutes",
                state.settings?.agentIdleMinutes ?? DEFAULT_IDLE_MINUTES,
                [5, 10, 30, 60],
                (minutes) => `${minutes} minutes`,
                (value) => ctx.run(actions.updateSettings({ agentIdleMinutes: value })),
              ),
            }),
          ]),
        )}
        ${renderAgentChoices(ctx, actions)}
      </div>`;
}

// Onboarding and Settings share one agent list, including live sign-in and
// installation status. There is no second catalog to keep in sync.
export function renderAgentChoices(ctx: EffectViewContext<object>, actions: AgentActions) {
  const state = actions.state;
  const direct = state.agents.filter((a) => !a.id.startsWith("acp:"));
  const registry = state.agents.filter((a) => a.id.startsWith("acp:"));
  const enabledRegistry = registry.filter((a) => a.enabled);
  const others = registry.filter((a) => !a.enabled);
  return htm`<div ...${column} gap="large">
        ${section("Your agents", "Enabled agents appear in the chat picker. You can change this anytime in Settings → Agents.", card(direct.map((a) => agentRow(ctx, actions, a))))}
        ${
          registry.length
            ? section(
                "More agents",
                "Connect another coding agent using its own account.",
                htm`
              <div ...${column} gap="small">
                ${enabledRegistry.length ? card(enabledRegistry.map((a) => agentRow(ctx, actions, a))) : null}
                <div ...${row}>
                  <button id="registry-agents" label=${state.showRegistry ? `Hide the other ${others.length}` : `Show the other ${others.length}`}
                    icon=${state.showRegistry ? "chevron-down" : "chevron-right"} small variant="ghost" onClick=${() => {
                      state.showRegistry = !state.showRegistry;
                      ctx.update();
                    }} />
                </div>
                ${
                  // At the same left edge as the enabled ones: the kernel's
                  // collapsible indented its body.
                  state.showRegistry ? card(others.map((a) => agentRow(ctx, actions, a))) : null
                }
              </div>`,
              )
            : null
        }
      </div>`;
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.3latestNov 21, 2026>=2 <439.8 KB7 permissionsListed
0.2.2Oct 25, 2026>=2 <439.3 KB7 permissionsListed
0.2.1Oct 23, 2026>=2 <439.2 KB7 permissionsListed
0.2.0Oct 5, 2026>=2 <324.7 KB7 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.