@frockbot/plugin-settings 0.0.0 → 0.1.1

package/src/client/bot-settings.ts

@@ -0,0 +1,150 @@
+import type {
+  ConnectionView,
+  ModelAssignment,
+  PackageInstallationView,
+} from "@frockbot/configuration-core";
+import type { PluginCatalogItem } from "@frockbot/plugin-shell/shared";
+
+export function isModelConnectionEligible(input: {
+  connection: ConnectionView;
+  packages: readonly PackageInstallationView[];
+  catalog: readonly PluginCatalogItem[];
+}): boolean {
+  const pkg = input.catalog.find(
+    (candidate) => candidate.packageId === input.connection.packageId,
+  );
+  const connectionType = pkg?.connectionTypes.find(
+    (candidate) => candidate.id === input.connection.connectionTypeId,
+  );
+  return Boolean(
+    input.connection.state === "ready" &&
+    input.packages.some(
+      (candidate) =>
+        candidate.packageId === input.connection.packageId &&
+        candidate.state === "installed",
+    ) &&
+    pkg?.capabilities.some(
+      (capability) =>
+        capability.kind === "model" &&
+        connectionType?.capabilities.includes(capability.id),
+    ),
+  );
+}
+
+export function resolveBotSettingsModel(input: {
+  current?: ModelAssignment;
+  useExactModel: boolean;
+  selectedModel: string;
+  exactConnectionId: string;
+  exactProviderModelId: string;
+}): ModelAssignment | undefined {
+  if (input.useExactModel) {
+    const selected = {
+      connectionId: input.exactConnectionId,
+      providerModelId: input.exactProviderModelId.trim(),
+    };
+    if (!selected.connectionId || !selected.providerModelId) {
+      throw new Error("A Connection and model ID are required");
+    }
+    return selected;
+  }
+  if (!input.selectedModel) return input.current;
+  let value: unknown;
+  try {
+    value = JSON.parse(input.selectedModel);
+  } catch {
+    throw new Error("A Connection and model ID are required");
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    typeof value[0] !== "string" ||
+    value[0].length === 0 ||
+    typeof value[1] !== "string" ||
+    value[1].length === 0
+  ) {
+    throw new Error("A Connection and model ID are required");
+  }
+  return { connectionId: value[0], providerModelId: value[1] };
+}
+
+export interface ModelSelectOption {
+  value: string;
+  label: string;
+}
+
+/** The Connections a model can be chosen from: ready, installed, model-capable. */
+export function eligibleModelConnections(input: {
+  connections: readonly ConnectionView[];
+  packages: readonly PackageInstallationView[];
+  catalog: readonly PluginCatalogItem[];
+}): ConnectionView[] {
+  return input.connections.filter((connection) =>
+    isModelConnectionEligible({
+      connection,
+      packages: input.packages,
+      catalog: input.catalog,
+    }),
+  );
+}
+
+/** One `<option>` per advertised model, shared by the Bot and User surfaces. */
+export function modelSelectOptions(
+  connections: readonly ConnectionView[],
+): ModelSelectOption[] {
+  return connections.flatMap((connection) =>
+    (connection.modelCatalog?.models ?? []).map((model) => ({
+      value: encodeModelSelection({
+        connectionId: connection.connectionId,
+        providerModelId: model.providerModelId,
+      }),
+      label: `${model.displayName} — ${connection.displayName}`,
+    })),
+  );
+}
+
+export function encodeModelSelection(model?: ModelAssignment): string {
+  return model
+    ? JSON.stringify([model.connectionId, model.providerModelId])
+    : "";
+}
+
+/** How a bound model reads in prose, e.g. "Llama 3 — Work". */
+export function describeModelAssignment(
+  model: ModelAssignment | undefined,
+  connections: readonly ConnectionView[],
+): string | undefined {
+  if (!model) return undefined;
+  const connection = connections.find(
+    (candidate) => candidate.connectionId === model.connectionId,
+  );
+  const catalogModel = connection?.modelCatalog?.models.find(
+    (candidate) => candidate.providerModelId === model.providerModelId,
+  );
+  const name = catalogModel?.displayName ?? model.providerModelId;
+  return connection ? `${name} — ${connection.displayName}` : name;
+}
+
+/** The inverse of {@link encodeModelSelection}; an empty value means no model. */
+export function decodeModelSelection(
+  value: string,
+): ModelAssignment | undefined {
+  if (!value) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("A Connection and model ID are required");
+  }
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length !== 2 ||
+    typeof parsed[0] !== "string" ||
+    parsed[0].length === 0 ||
+    typeof parsed[1] !== "string" ||
+    parsed[1].length === 0
+  ) {
+    throw new Error("A Connection and model ID are required");
+  }
+  return { connectionId: parsed[0], providerModelId: parsed[1] };
+}

package/src/client/index.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "bun:test";
+import {
+  clientSurfaceRegistryKey,
+  type ClientPluginContext,
+  type ClientSlotRegistration,
+} from "@frockbot/client-core";
+import { createClientSurfaceRegistry } from "@frockbot/client-ui";
+import { settingsClientPlugin } from "./index.js";
+import {
+  assignmentHasPendingOperation,
+  projectAssignmentOperations,
+} from "./assignment-operations.js";
+
+describe("settings client contribution", () => {
+  it("projects every Assignment operation without catalog ownership", () => {
+    const operations = [
+      {
+        commandId: "assign-1",
+        kind: "assigning" as const,
+        assignmentId: "orphan-assign",
+        state: "retrying" as const,
+        target: {
+          assignmentId: "orphan-assign",
+          packageId: "missing-package",
+          capabilityId: "missing-capability",
+        },
+      },
+      {
+        commandId: "replace-1",
+        kind: "replacing" as const,
+        assignmentId: "orphan-replace",
+        state: "pending" as const,
+      },
+      {
+        commandId: "unassign-1",
+        kind: "unassigning" as const,
+        assignmentId: "orphan-unassign",
+        state: "retrying" as const,
+      },
+    ];
+    const projected = projectAssignmentOperations({
+      assignmentOperations: operations,
+    });
+    expect(projected).toEqual(operations);
+    expect(projected).not.toBe(operations);
+    expect(assignmentHasPendingOperation(projected, "orphan-unassign")).toBe(
+      true,
+    );
+    expect(assignmentHasPendingOperation(projected, "stable")).toBe(false);
+  });
+
+  it("registers feature surfaces and shell-owned trigger seats", () => {
+    const surfaces = createClientSurfaceRegistry();
+    const slots: ClientSlotRegistration[] = [];
+    const provided: unknown[] = [];
+    const context: ClientPluginContext = {
+      transport: {
+        turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      },
+      inject: (key) => {
+        if (key !== clientSurfaceRegistryKey) {
+          throw new Error("unexpected client provider");
+        }
+        return surfaces as never;
+      },
+      provide: (key) => {
+        provided.push(key);
+        return () => {};
+      },
+      slot: (registration) => {
+        slots.push(registration);
+        return () => slots.splice(slots.indexOf(registration), 1);
+      },
+    };
+
+    const result = settingsClientPlugin(context);
+    if (!Array.isArray(result)) throw new Error("expected owned registrations");
+
+    expect(slots.map((slot) => slot.slot)).toEqual([
+      "frockbot.sidebar-actions",
+      "frockbot.user-profile",
+      "frockbot.right-panel",
+      "frockbot.bot-actions",
+    ]);
+    // Composition is an internal detail the Settings Package no longer shows,
+    // so it provides no client state of its own.
+    expect(provided).toEqual([]);
+    for (const id of [
+      "bot-settings",
+      "plugins",
+      "models",
+      "connections",
+      "package-catalog",
+      "user-settings",
+    ]) {
+      expect(surfaces.has(id)).toBe(true);
+    }
+
+    for (const dispose of result.toReversed()) dispose();
+    expect(slots).toEqual([]);
+    expect(surfaces.active.value).toBeUndefined();
+    for (const id of [
+      "bot-settings",
+      "plugins",
+      "models",
+      "connections",
+      "package-catalog",
+      "user-settings",
+    ]) {
+      expect(surfaces.has(id)).toBe(false);
+    }
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,78 @@
+/// <reference path="../env.d.ts" />
+
+import {
+  clientSurfaceRegistryKey,
+  type ClientPlugin,
+} from "@frockbot/client-core";
+import BotPanel from "./BotPanel.vue";
+import BotSettingsSurface from "./BotSettingsSurface.vue";
+import BotSettingsTrigger from "./BotSettingsTrigger.vue";
+import ConnectionsSurface from "./ConnectionsSurface.vue";
+import ModelsSurface from "./ModelsSurface.vue";
+import PluginsSurface from "./PluginsSurface.vue";
+import PackageCatalogSurface from "./PackageCatalogSurface.vue";
+import PluginsTrigger from "./PluginsTrigger.vue";
+import UserProfileTrigger from "./UserProfileTrigger.vue";
+import UserSettingsSurface from "./UserSettingsSurface.vue";
+
+export const settingsClientPlugin: ClientPlugin = (ctx) => {
+  const surfaces = ctx.inject(clientSurfaceRegistryKey);
+  return [
+    surfaces.register({
+      id: "bot-settings",
+      title: "Settings",
+      component: BotSettingsSurface,
+      placement: "panel",
+    }),
+    // Enablement and configuration are separate surfaces: Plugins turns a
+    // Package on and off, Models configures model providers and picks the
+    // model, and Connections authorizes the accounts a Bot may be given.
+    surfaces.register({
+      id: "plugins",
+      title: "Plugins",
+      component: PluginsSurface,
+    }),
+    surfaces.register({
+      id: "models",
+      title: "Models",
+      component: ModelsSurface,
+    }),
+    surfaces.register({
+      id: "connections",
+      title: "Connections",
+      component: ConnectionsSurface,
+    }),
+    surfaces.register({
+      id: "package-catalog",
+      title: "Package Catalog",
+      component: PackageCatalogSurface,
+    }),
+    surfaces.register({
+      id: "user-settings",
+      title: "Application settings",
+      component: UserSettingsSurface,
+    }),
+    ctx.slot({
+      slot: "frockbot.sidebar-actions",
+      order: 10,
+      component: PluginsTrigger,
+    }),
+    ctx.slot({
+      slot: "frockbot.user-profile",
+      order: 10,
+      component: UserProfileTrigger,
+    }),
+    ctx.slot({
+      slot: "frockbot.right-panel",
+      order: 10,
+      component: BotPanel,
+    }),
+    ctx.slot({
+      slot: "frockbot.bot-actions",
+      order: 10,
+      component: BotSettingsTrigger,
+    }),
+  ];
+};
+
+export default settingsClientPlugin;

package/src/client/package-settings.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
+import {
+  collectSettingsValues,
+  seedSettingsDraft,
+  settingFieldKind,
+  settingLabel,
+} from "./package-settings.js";
+
+function definition(
+  id: string,
+  schema: PackageSettingDefinition["schema"],
+): PackageSettingDefinition {
+  return { id, schemaVersion: 1, scopes: ["user"], schema };
+}
+
+const definitions = [
+  definition("model", { type: "string", title: "Model", enum: ["a", "b"] }),
+  definition("enabled", { type: "boolean" }),
+  definition("results", { type: "integer", title: "Web search results" }),
+  definition("prefix", { type: "string" }),
+];
+
+describe("generated Package settings", () => {
+  test("derives a control from the declared schema", () => {
+    expect(definitions.map((entry) => settingFieldKind(entry.schema))).toEqual([
+      "enum",
+      "boolean",
+      "number",
+      "text",
+    ]);
+    expect(settingLabel(definitions[0]!)).toBe("Model");
+    // A schema with no title is named by its own id rather than by a label a
+    // surface invented for it.
+    expect(settingLabel(definitions[1]!)).toBe("enabled");
+  });
+
+  test("seeds the draft from durable values and neutral empties", () => {
+    expect(seedSettingsDraft(definitions, { model: "b", results: 7 })).toEqual({
+      model: "b",
+      enabled: false,
+      results: 7,
+      prefix: "",
+    });
+  });
+
+  test("sends only the fields the User filled in", () => {
+    expect(
+      collectSettingsValues(definitions, {
+        model: "",
+        enabled: true,
+        results: "9",
+        prefix: "hello",
+      }),
+    ).toEqual({ enabled: true, results: 9, prefix: "hello" });
+  });
+
+  test("drops a number that is not one", () => {
+    expect(
+      collectSettingsValues(definitions, { results: "not a number" }),
+    ).toEqual({ enabled: false });
+  });
+});

package/src/client/package-settings.ts

@@ -0,0 +1,77 @@
+import type {
+  PackageSettingDefinition,
+  PackageSettingSchema,
+} from "@frockbot/kernel-composition";
+
+/**
+ * The generated Package settings form, minus the rendering.
+ *
+ * The fields come from the schema each Package declares, so a Package that
+ * adds a setting gets a control with no edit to a surface: the manifest is the
+ * only description of the knob that exists.
+ */
+export type SettingFieldKind = "enum" | "boolean" | "number" | "text";
+
+export function settingFieldKind(
+  schema: PackageSettingSchema,
+): SettingFieldKind {
+  if (schema.enum && schema.enum.length > 0) return "enum";
+  if (schema.type === "boolean") return "boolean";
+  if (schema.type === "number" || schema.type === "integer") return "number";
+  return "text";
+}
+
+export function settingLabel(definition: PackageSettingDefinition): string {
+  return definition.schema.title ?? definition.id;
+}
+
+/** A draft seeded from durable state, so an untouched field saves unchanged. */
+export function seedSettingsDraft(
+  definitions: readonly PackageSettingDefinition[],
+  stored: Record<string, unknown>,
+): Record<string, string | number | boolean> {
+  const draft: Record<string, string | number | boolean> = {};
+  for (const definition of definitions) {
+    const value = stored[definition.id];
+    if (
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      draft[definition.id] = value;
+      continue;
+    }
+    draft[definition.id] =
+      settingFieldKind(definition.schema) === "boolean" ? false : "";
+  }
+  return draft;
+}
+
+/**
+ * The command payload. Only the fields the User filled in are sent: the
+ * command is a partial update, and an empty text or number box means "leave
+ * this one alone" rather than "store an empty string".
+ */
+export function collectSettingsValues(
+  definitions: readonly PackageSettingDefinition[],
+  draft: Record<string, string | number | boolean | undefined>,
+): Record<string, string | number | boolean> {
+  const values: Record<string, string | number | boolean> = {};
+  for (const definition of definitions) {
+    const kind = settingFieldKind(definition.schema);
+    const raw = draft[definition.id];
+    if (kind === "boolean") {
+      values[definition.id] = raw === true;
+      continue;
+    }
+    if (raw === "" || raw === undefined) continue;
+    if (kind === "number") {
+      const parsed = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isFinite(parsed)) continue;
+      values[definition.id] = parsed;
+      continue;
+    }
+    values[definition.id] = String(raw);
+  }
+  return values;
+}

package/src/client/package-surfaces.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, test } from "bun:test";
+import type { PackageInstallationView } from "@frockbot/configuration-core";
+import type { PluginCatalogItem } from "@frockbot/plugin-shell/shared";
+import {
+  configurablePackages,
+  configurationHomeLabel,
+  isPackageEnabled,
+  isPackageInstalled,
+  packageConfigurationHome,
+  packagesForHome,
+} from "./package-surfaces.js";
+
+function catalogItem(
+  overrides: Partial<PluginCatalogItem> & { packageId: string },
+): PluginCatalogItem {
+  return {
+    displayName: overrides.packageId,
+    version: "0.0.1",
+    capabilities: [],
+    connectionTypes: [],
+    ...overrides,
+  };
+}
+
+const provider = catalogItem({
+  packageId: "provider-ollama-cloud",
+  capabilities: [
+    { id: "ollama-cloud-models", kind: "model", connectionTypes: ["account"] },
+    {
+      id: "ollama-cloud-web-search",
+      kind: "tool",
+      connectionTypes: ["account"],
+    },
+  ],
+  connectionTypes: [
+    {
+      id: "account",
+      displayName: "Ollama Cloud account",
+      allowMultiple: true,
+      authorizationKind: "api-key",
+      capabilities: ["ollama-cloud-models"],
+    },
+  ],
+});
+
+const connector = catalogItem({
+  packageId: "composio",
+  capabilities: [
+    { id: "gmail-tools", kind: "tool", connectionTypes: ["gmail"] },
+  ],
+  connectionTypes: [
+    {
+      id: "gmail",
+      displayName: "Gmail",
+      allowMultiple: false,
+      authorizationKind: "grant",
+      capabilities: ["gmail-tools"],
+    },
+  ],
+});
+
+const settingsOnly = catalogItem({
+  packageId: "image",
+  capabilities: [{ id: "image-tools", kind: "tool", connectionTypes: [] }],
+  settings: [
+    {
+      id: "model",
+      schemaVersion: 1,
+      scopes: ["user"],
+      schema: { type: "string", title: "Model" },
+    },
+  ] as PluginCatalogItem["settings"],
+});
+
+const plain = catalogItem({
+  packageId: "web",
+  capabilities: [{ id: "web-tools", kind: "tool", connectionTypes: [] }],
+});
+
+const catalog = [provider, connector, settingsOnly, plain];
+
+function installation(
+  packageId: string,
+  state: PackageInstallationView["state"],
+): PackageInstallationView {
+  return { packageId, version: "0.0.1", state };
+}
+
+describe("Package configuration homes", () => {
+  test("routes every declared Package to exactly one home", () => {
+    expect(packageConfigurationHome(provider)).toBe("models");
+    expect(packageConfigurationHome(connector)).toBe("connections");
+    expect(packageConfigurationHome(settingsOnly)).toBe("user-settings");
+    // Nothing declared is nothing to configure: the Package appears in Plugins
+    // to be enabled and disabled, and on no configuration surface at all.
+    expect(packageConfigurationHome(plain)).toBe("none");
+
+    const homed = catalog.flatMap((item) => {
+      const home = packageConfigurationHome(item);
+      return home === "none" ? [] : [[item.packageId, home] as const];
+    });
+    expect(homed).toEqual([
+      ["provider-ollama-cloud", "models"],
+      ["composio", "connections"],
+      ["image", "user-settings"],
+    ]);
+  });
+
+  test("a model provider that declares Connections is Models', not Connections'", () => {
+    expect(packagesForHome(catalog, "models")).toEqual([provider]);
+    expect(packagesForHome(catalog, "connections")).toEqual([connector]);
+    expect(packagesForHome(catalog, "user-settings")).toEqual([settingsOnly]);
+  });
+
+  test("only an installed and enabled Package is configurable", () => {
+    const packages = [
+      installation("provider-ollama-cloud", "installed"),
+      installation("composio", "disabled"),
+      installation("image", "failed"),
+    ];
+    expect(
+      configurablePackages({ catalog, packages, home: "models" }).map(
+        (item) => item.packageId,
+      ),
+    ).toEqual(["provider-ollama-cloud"]);
+    // A disabled Package keeps its Connections and settings; it just stops
+    // being configurable until Plugins enables it again.
+    expect(
+      configurablePackages({ catalog, packages, home: "connections" }),
+    ).toEqual([]);
+    expect(
+      configurablePackages({ catalog, packages, home: "user-settings" }),
+    ).toEqual([]);
+    expect(isPackageEnabled(packages, "composio")).toBe(false);
+    expect(isPackageInstalled(packages, "composio")).toBe(true);
+    expect(isPackageInstalled(packages, "web")).toBe(false);
+  });
+
+  test("names the surface a Plugins row points at", () => {
+    expect(configurationHomeLabel("models")).toBe("Models");
+    expect(configurationHomeLabel("connections")).toBe("Connections");
+    expect(configurationHomeLabel("user-settings")).toBe(
+      "Application settings",
+    );
+    expect(configurationHomeLabel("none")).toBeUndefined();
+  });
+});