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

Permissions in 0.2.3

  • 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

onboarding.ts8.3 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.
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 "convergence/effect";
import type { PluginSummary, Settings, ViewHandle, Workspace } from "convergence";
import type { AgentEntry } from "./controller.ts";
import { ChatImport } from "./chat-import.ts";

export const STEPS = ["Discover", "Agents", "Workspace", "Plugins"] as const;
export const Progress = z.object({
  done: z.boolean(),
  step: z.number().int().min(0).max(3),
  workspaceId: z.string().nullable(),
  returning: z.boolean().default(false),
});
const KEY = "onboarding";

const makeOnboarding = Effect.fn("Onboarding.make")(function* () {
  const host = yield* Host;
  const app = yield* App;
  const kernel = yield* Kernel;
  const plugin = yield* Plugin;
  const notify = yield* Notify;
  const imports = yield* ChatImport;
  const state = {
    done: false, step: 0, workspaceId: null as string | null, returning: false,
    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,
  };
  const pluginChoices = new Set<string>();
  const views: ViewHandle[] = [];
  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, returning: state.returning },
  });
  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 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;
    for (const p of state.plugins) if ((p.official && (p.disabledByDefault || !p.enabled)) || p.source === "marketplace") pluginChoices.add(p.name);
    if (!state.workspaces.some((w) => w.id === state.workspaceId)) state.workspaceId = null;
    state.ready = true;
    redraw();
  });
  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 !== "puzzle")) {
        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 (state.returning) return;
    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.returning = false;
    state.active = true;
    yield* save();
    yield* app.route("onboarding");
    yield* refresh();
  }));
  const resume = () => run("load", Effect.gen(function* () {
    state.returning = 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 === 3) yield* imports.refresh();
    state.step = step;
    yield* save();
  }));
  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 });
    state.workspaceId = workspace.id;
    yield* save();
    yield* refresh();
    yield* imports.refresh();
  }));
  const setAgentEnabled = (agent: AgentEntry, enabled: boolean) => run(`agent:${agent.id}`, Effect.gen(function* () {
    yield* host.call("host/agents.set_enabled", { agentId: agent.id, enabled });
    yield* refresh();
  }));
  const signIn = (agent: AgentEntry, method: { readonly id: string }) => run(`auth:${agent.id}`, Effect.gen(function* () {
    yield* host.call("host/agents.authenticate", { agentId: agent.id, method: method.id });
    yield* refresh();
  }));
  const updateAgent = (agent: AgentEntry) => run(`update:${agent.id}`, Effect.gen(function* () {
    yield* host.call("host/agents.update", { agentId: agent.id });
    yield* refresh();
  }));
  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 reviewPlugin = (name: string) => run(`plugin:${name}`, Effect.gen(function* () {
    yield* host.call("host/plugins.request_enable", { name });
    yield* refresh();
  }));
  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 browsePlugins = () => run("market", Effect.gen(function* () {
    state.returning = true;
    yield* save(false);
    state.done = false;
    yield* app.route("market");
  }));
  const finish = (startChat: boolean) => run("finish", Effect.gen(function* () {
    const agent = state.agents.find((a) => a.enabled && a.status?.state === "ready");
    const chat = startChat && agent && state.workspaceId
      ? yield* host.call("host/chats.create", { workspaceId: state.workspaceId, agentId: agent.id })
      : null;
    state.returning = false;
    yield* save(true);
    state.done = true;
    if (chat) yield* app.update({ route: "chat", workspaceId: chat.workspaceId, chatId: chat.id, shared: { selectedChat: chat } });
    else yield* app.route("chat");
  }));
  return {
    state, views, redraw, imports, pluginChoices,
    initialize: () => initialize().pipe(Effect.catch((error) => notify.error(`Could not load onboarding: ${error.message}`))),
    enter, restart, resume, move, chooseWorkspace, addWorkspace, setAgentEnabled, signIn, updateAgent, changeAppearance, finish,
    reviewPlugin, setPluginEnabled, browsePlugins,
    retry: () => run("load", refresh()),
    refresh: () => state.active ? refresh().pipe(Effect.catch((error) => Effect.sync(() => { state.error = error.message; 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.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.