@agent-native/toolkit 0.23.1 → 0.198.2

package/src/app/settings/api-keys/api-keys-state.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure derivations for Settings › API keys from the `list-api-keys` read.
+ * Components render these; nothing here fetches.
+ */
+
+import {
+  AGENT_PROVIDER_CATALOG,
+  type AgentProviderId,
+} from "@agent-native/core/client/agent-provider-catalog";
+import type {
+  AddableApiKey,
+  ApiKeyEntry,
+  ApiKeysListing,
+} from "@agent-native/core/secrets/api-keys";
+import { secretKeyNames } from "@agent-native/core/secrets/key-aliases";
+
+import { normalizeKeyName } from "../NewKeyMenu.js";
+
+export type { AddableApiKey, ApiKeyEntry, ApiKeysListing };
+
+/** Calendar tokens exist only once someone connects a calendar in Meetings. */
+export const MEETINGS_LAB_KEY = "clips.meetings";
+const MEETINGS_MANAGER_ID = "meetings";
+
+export interface ApiKeyGroups {
+  personal: ApiKeyEntry[];
+  org: ApiKeyEntry[];
+  managed: ApiKeyEntry[];
+}
+
+export function groupApiKeys(
+  listing: ApiKeysListing,
+  labs: Readonly<Record<string, boolean>>,
+): ApiKeyGroups {
+  return {
+    personal: listing.keys.filter((entry) => entry.scope === "user"),
+    org: listing.keys.filter((entry) => entry.scope === "org"),
+    managed: listing.managed.filter(
+      (entry) =>
+        entry.managedBy?.id !== MEETINGS_MANAGER_ID || !!labs[MEETINGS_LAB_KEY],
+    ),
+  };
+}
+
+/** A managed key's owner page, from its `page` or `page/sub` route. */
+export function settingsRouteParts(route: string): {
+  page: string;
+  sub?: string;
+} {
+  const [page = "", sub] = route.split("/").filter(Boolean);
+  return sub ? { page, sub } : { page };
+}
+
+/**
+ * Row anchor. Legacy `secrets:KEY` links land on the caller's own row; other
+ * rows carry their scope so a name saved twice gets two ids.
+ */
+export function apiKeyRowId(entry: ApiKeyEntry): string {
+  return entry.scope === "user" && entry.storedScope === "user"
+    ? `secrets:${entry.name}`
+    : `secrets:${entry.scope}-${entry.storedScope}:${entry.name}`;
+}
+
+export function apiKeyEntryId(entry: ApiKeyEntry): string {
+  return `${entry.scope}:${entry.storedScope}:${entry.name}`;
+}
+
+/** Features other than the agent's models, which read as "Model" instead. */
+export function usedByFeatures(entry: ApiKeyEntry): string[] {
+  const features = entry.usedFor
+    .filter((usage) => !(entry.provider && usage.feature === "Agent"))
+    .map((usage) => usage.feature);
+  return [...new Set(features)];
+}
+
+export function providerForKeyName(name: string): AgentProviderId | null {
+  return (
+    AGENT_PROVIDER_CATALOG.find(
+      (option) =>
+        (option.key && secretKeyNames(option.key).includes(name)) ||
+        option.endpointKey === name,
+    )?.id ?? null
+  );
+}
+
+export type AddKeyTarget =
+  | { kind: "empty" }
+  | { kind: "provider"; provider: AgentProviderId }
+  | { kind: "managed"; owner: string }
+  | { kind: "registered"; key: AddableApiKey }
+  | { kind: "custom"; name: string };
+
+/** What saving a typed name would do, before the value is sent. */
+export function addKeyTarget(
+  rawName: string,
+  listing: ApiKeysListing,
+): AddKeyTarget {
+  const name = normalizeKeyName(rawName);
+  if (!name) return { kind: "empty" };
+  const provider = providerForKeyName(name);
+  if (provider) return { kind: "provider", provider };
+  const managed = listing.managed.find((entry) => entry.name === name);
+  if (managed?.managedBy) {
+    return { kind: "managed", owner: managed.managedBy.owner };
+  }
+  const registered = listing.addable.find((key) => key.name === name);
+  if (registered) return { kind: "registered", key: registered };
+  const saved = listing.keys.find((entry) => entry.name === name);
+  if (saved?.registered) {
+    return {
+      kind: "registered",
+      key: {
+        name,
+        label: saved.label ?? name,
+        ...(saved.docsUrl ? { docsUrl: saved.docsUrl } : {}),
+        scope: saved.storedScope,
+      },
+    };
+  }
+  return { kind: "custom", name };
+}
+
+/** Registered keys matching a partly typed name, for the Name suggestions. */
+export function addableSuggestions(
+  rawName: string,
+  listing: ApiKeysListing,
+  limit = 4,
+): AddableApiKey[] {
+  const query = rawName.trim().toLowerCase();
+  if (!query) return [];
+  const normalized = normalizeKeyName(rawName);
+  return listing.addable
+    .filter(
+      (key) =>
+        key.name !== normalized &&
+        (key.name.toLowerCase().includes(query) ||
+          key.label.toLowerCase().includes(query)),
+    )
+    .slice(0, limit);
+}
+
+/** A `#secrets:KEY` hash names a key; the page scrolls to it or offers to add it. */
+export function secretKeyFromHash(hash: string): string | null {
+  const match = /^#?secrets:([A-Za-z0-9_-]+)$/.exec(hash.trim());
+  return match?.[1] ?? null;
+}

package/src/app/settings/app-group/AppDefaultModelRow.tsx

@@ -0,0 +1,241 @@
+import {
+  fetchAppModelDefault,
+  resetAppModelDefault,
+  saveAppModelDefault,
+  type AppModelDefaultState,
+} from "@agent-native/core/client/app-model-default";
+import { useChangeVersions } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { Button } from "@agent-native/toolkit/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "@agent-native/toolkit/ui/select";
+import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+
+import { friendlyModelName } from "../SettingsPanel.js";
+import { SettingsRow } from "../SettingsRow.js";
+import { ReadOnlySettingValue } from "./ReadOnlySettingValue.js";
+
+const USE_DEFAULT = "__default__";
+const QUERY_KEY = ["agent-native", "app-model-default"] as const;
+
+function optionValue(engine: string, model: string): string {
+  return `${engine}::${model}`;
+}
+
+function parseOption(value: string): { engine: string; model: string } | null {
+  const separator = value.indexOf("::");
+  if (separator < 1) return null;
+  return {
+    engine: value.slice(0, separator),
+    model: value.slice(separator + 2),
+  };
+}
+
+interface ModelGroup {
+  engine: string;
+  label: string;
+  models: string[];
+}
+
+function providerLabel(engine: { name: string; label: string }): string {
+  return engine.name === "builder" ? "Builder.io" : engine.label || engine.name;
+}
+
+/**
+ * Providers the app can default to: the configured ones, plus whatever the
+ * saved default names, so a value set before a key was removed still shows.
+ */
+function modelGroups(state: AppModelDefaultState): ModelGroup[] {
+  const groups: ModelGroup[] = [];
+  for (const engine of state.engines) {
+    const selected = engine.name === state.engine ? state.model : null;
+    const usable =
+      engine.configured &&
+      engine.packageInstalled !== false &&
+      // Anthropic is listed twice (native and AI SDK); offer one.
+      engine.name !== "ai-sdk:anthropic";
+    if (!usable && !selected) continue;
+    const models = engine.supportedModels.length
+      ? [...engine.supportedModels]
+      : [engine.defaultModel];
+    if (selected && !models.includes(selected)) models.unshift(selected);
+    groups.push({ engine: engine.name, label: providerLabel(engine), models });
+  }
+  return groups;
+}
+
+function orgDefaultModelName(state: AppModelDefaultState): string | null {
+  const orgDefault = state.orgDefault;
+  if (!orgDefault) return null;
+  const model =
+    orgDefault.model ??
+    state.engines.find((engine) => engine.name === orgDefault.engine)
+      ?.defaultModel;
+  return model ? friendlyModelName(model) : null;
+}
+
+/**
+ * Agent › Default model on the app's General page: the model new chats in
+ * this app use, over the organization's default. Owners and admins change
+ * it; everyone else sees the value. The agent sets the same value with
+ * `manage-agent-engine` (`set-app-default`, `reset-app-default`).
+ */
+export function AppDefaultModelRow({ appName }: { appName: string }) {
+  const t = useT();
+  const queryClient = useQueryClient();
+  // The agent changes this through an action, not this route.
+  const version = useChangeVersions(["settings", "action"]);
+  const query = useQuery({
+    queryKey: [...QUERY_KEY, version],
+    queryFn: fetchAppModelDefault,
+    placeholderData: (previous) => previous,
+  });
+  const [pending, setPending] = useState<string | null>(null);
+  const mutation = useMutation({
+    mutationFn: (value: string) => {
+      const selection = parseOption(value);
+      return selection
+        ? saveAppModelDefault(selection)
+        : resetAppModelDefault();
+    },
+    onMutate: (value) => setPending(value),
+    onSuccess: (next) => {
+      queryClient.setQueriesData({ queryKey: QUERY_KEY }, next);
+    },
+    onSettled: () => setPending(null),
+  });
+  const state = query.data;
+  const groups = useMemo(() => (state ? modelGroups(state) : []), [state]);
+  const label = t("agentChat.settingsShell.appGroup.defaultModel");
+
+  if (!state) {
+    if (query.isError) {
+      return (
+        <SettingsRow
+          id="app-models"
+          label={label}
+          description={t(
+            "agentChat.settingsShell.appGroup.defaultModelLoadError",
+          )}
+          control={
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => void query.refetch()}
+            >
+              {t("agentChat.settingsShell.appGroup.retry")}
+            </Button>
+          }
+        />
+      );
+    }
+    // SettingsRow's shape; its description is a <p>, which can't hold a
+    // Skeleton's <div>.
+    return (
+      <div
+        id="app-models"
+        role="status"
+        aria-busy="true"
+        aria-label={label}
+        className="agent-native-settings-row px-5 py-4 sm:px-6"
+      >
+        <div className="agent-native-settings-row__layout flex flex-col gap-3">
+          <div className="agent-native-settings-row__main flex min-w-0 flex-1 flex-col gap-2">
+            <span className="text-sm font-medium text-foreground">{label}</span>
+            <Skeleton className="h-3.5 w-72 max-w-full" />
+          </div>
+          <div className="agent-native-settings-row__control max-w-full shrink-0">
+            <Skeleton className="h-8 w-64" />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const saved =
+    state.source !== "default" && state.engine && state.model
+      ? optionValue(state.engine, state.model)
+      : USE_DEFAULT;
+  const value = pending ?? saved;
+  const selected = parseOption(value);
+  const selectedLabel = selected
+    ? friendlyModelName(selected.model)
+    : t("agentChat.settingsShell.appGroup.useDefault");
+  const orgDefault = orgDefaultModelName(state);
+  const description = orgDefault
+    ? t("agentChat.settingsShell.appGroup.defaultModelDescription", {
+        app: appName,
+        model: orgDefault,
+      })
+    : t("agentChat.settingsShell.appGroup.defaultModelDescriptionUnset", {
+        app: appName,
+      });
+
+  return (
+    <SettingsRow
+      id="app-models"
+      label={label}
+      description={
+        <>
+          {description}
+          {mutation.isError ? (
+            <span role="alert" className="block text-destructive">
+              {t("agentChat.settingsShell.appGroup.defaultModelSaveError")}
+            </span>
+          ) : null}
+        </>
+      }
+      control={
+        state.canUpdate ? (
+          <Select
+            value={value}
+            onValueChange={(next) => {
+              if (next !== value) mutation.mutate(next);
+            }}
+          >
+            <SelectTrigger size="sm" className="w-64" aria-label={label}>
+              <SelectValue>{selectedLabel}</SelectValue>
+            </SelectTrigger>
+            <SelectContent>
+              <SelectGroup>
+                <SelectItem value={USE_DEFAULT}>
+                  {t("agentChat.settingsShell.appGroup.useDefault")}
+                </SelectItem>
+              </SelectGroup>
+              {groups.length > 0 ? <SelectSeparator /> : null}
+              {groups.map((group) => (
+                <SelectGroup key={group.engine}>
+                  <SelectLabel>{group.label}</SelectLabel>
+                  {group.models.map((model) => (
+                    <SelectItem
+                      key={model}
+                      value={optionValue(group.engine, model)}
+                    >
+                      {friendlyModelName(model)}
+                    </SelectItem>
+                  ))}
+                </SelectGroup>
+              ))}
+            </SelectContent>
+          </Select>
+        ) : (
+          <ReadOnlySettingValue
+            value={selectedLabel}
+            reason={t("agentChat.settingsShell.appGroup.adminOnly")}
+          />
+        )
+      }
+    />
+  );
+}

package/src/app/settings/app-group/ReadOnlySettingValue.tsx

@@ -0,0 +1,33 @@
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@agent-native/toolkit/ui/tooltip";
+import { IconLock } from "@tabler/icons-react";
+
+/** A setting the viewer can see but not change, with who can in a tooltip. */
+export function ReadOnlySettingValue({
+  value,
+  reason,
+}: {
+  value: string;
+  reason: string;
+}) {
+  return (
+    <TooltipProvider delayDuration={200}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <span
+            tabIndex={0}
+            className="inline-flex items-center gap-1.5 whitespace-nowrap rounded-sm text-sm text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {value}
+            <IconLock className="size-3.5 shrink-0" aria-hidden="true" />
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>{reason}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/src/app/settings/app-group/SettingsHeaderBadge.tsx

@@ -0,0 +1,34 @@
+import { Badge } from "@agent-native/toolkit/ui/badge";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@agent-native/toolkit/ui/tooltip";
+
+/** The chip beside a Settings page title, with its explanation in a tooltip. */
+export function SettingsHeaderBadge({
+  label,
+  tooltip,
+}: {
+  label: string;
+  tooltip?: string;
+}) {
+  const badge = <Badge variant="outline">{label}</Badge>;
+  if (!tooltip) return badge;
+  return (
+    <TooltipProvider delayDuration={200}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <span
+            tabIndex={0}
+            className="inline-flex rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {badge}
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>{tooltip}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/src/app/settings/app-settings-tabs.ts

@@ -0,0 +1,65 @@
+import { IconBell } from "@tabler/icons-react";
+import type { ReactNode } from "react";
+
+import type {
+  SettingsAppArea,
+  SettingsSearchEntry,
+  SettingsTabItem,
+} from "./SettingsTabsPage.js";
+
+export interface AppSettingsTabsInput {
+  appAreas?: readonly SettingsAppArea[];
+  notifications?: ReactNode;
+  notificationsLabel?: string;
+  notificationsSearchEntries?: readonly SettingsSearchEntry[];
+}
+
+export const NOTIFICATIONS_SETTINGS_TAB_ID = "notifications";
+
+/**
+ * `extraTabs` plus the tabs the app-group props stand for, so today's tabs and
+ * the redesigned shell read one list: `notifications` becomes the tab the
+ * Notifications page claims, and each visible app area a tab placed on the
+ * app's General page. A template tab with the same id wins, so a template
+ * mid-migration never shows one twice.
+ */
+export function withAppSettingsTabs(
+  extraTabs: readonly SettingsTabItem[] | undefined,
+  input: AppSettingsTabsInput,
+  notificationsFallbackLabel: string,
+): SettingsTabItem[] {
+  const tabs = [...(extraTabs ?? [])];
+  const taken = new Set(tabs.map((tab) => tab.id));
+  if (
+    input.notifications != null &&
+    !taken.has(NOTIFICATIONS_SETTINGS_TAB_ID)
+  ) {
+    taken.add(NOTIFICATIONS_SETTINGS_TAB_ID);
+    tabs.unshift({
+      id: NOTIFICATIONS_SETTINGS_TAB_ID,
+      label: input.notificationsLabel ?? notificationsFallbackLabel,
+      icon: IconBell,
+      group: "app",
+      keywords: "notifications email alerts",
+      searchEntries: input.notificationsSearchEntries
+        ? [...input.notificationsSearchEntries]
+        : undefined,
+      content: input.notifications,
+    });
+  }
+  for (const area of input.appAreas ?? []) {
+    if (area.visible === false || taken.has(area.id)) continue;
+    taken.add(area.id);
+    tabs.push({
+      id: area.id,
+      label: area.label,
+      icon: area.icon,
+      group: "app",
+      keywords: area.keywords,
+      searchEntries: area.searchEntries,
+      settingsPlacement: "app-area",
+      content: area.content,
+    });
+  }
+  return tabs;
+}

package/src/app/settings/deferred-builder-connect-popover.tsx

@@ -0,0 +1,30 @@
+import { cloneElement, lazy, Suspense } from "react";
+
+import { LazyChunkErrorBoundary } from "../shared/LazyChunkErrorBoundary.js";
+import { LazyChunkRetryFallback } from "../shared/LazyChunkRetryFallback.js";
+import type { BuilderConnectPopoverProps } from "./BuilderConnectPopover.js";
+
+const LazyBuilderConnectPopover = lazy(() =>
+  import("./BuilderConnectPopover.js").then((module) => ({
+    default: module.BuilderConnectPopover,
+  })),
+);
+
+export { LazyChunkRetryFallback } from "../shared/LazyChunkRetryFallback.js";
+
+export function DeferredBuilderConnectPopover(
+  props: BuilderConnectPopoverProps,
+) {
+  return (
+    <LazyChunkErrorBoundary fallback={<LazyChunkRetryFallback />}>
+      <Suspense
+        fallback={cloneElement(props.children, {
+          disabled: true,
+          "aria-busy": true,
+        })}
+      >
+        <LazyBuilderConnectPopover {...props} />
+      </Suspense>
+    </LazyChunkErrorBoundary>
+  );
+}

package/src/app/settings/extension-settings-capability.spec.ts

@@ -0,0 +1,16 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+
+import { areExtensionSettingsEnabled } from "./SettingsPanel.js";
+
+describe("areExtensionSettingsEnabled", () => {
+  it("keeps extension management out of Settings by default", () => {
+    expect(areExtensionSettingsEnabled()).toBe(false);
+    expect(areExtensionSettingsEnabled({ extensionTools: false })).toBe(false);
+  });
+
+  it("allows hosts to opt into extension management", () => {
+    expect(areExtensionSettingsEnabled({ extensionTools: true })).toBe(true);
+  });
+});

package/src/app/settings/index.node-esm.spec.ts

@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { expect, it } from "vitest";
+
+it("re-exports the settings shell through a Node ESM file path", async () => {
+  const source = await readFile(new URL("./index.ts", import.meta.url), "utf8");
+  const shellReexport = source.match(/export\s+\*\s+from\s+["']([^"']+)["'];/);
+  expect(shellReexport?.[1]).toBe("./shell/index.js");
+
+  const fixture = await mkdtemp(path.join(tmpdir(), "toolkit-settings-esm-"));
+  try {
+    await writeFile(
+      path.join(fixture, "package.json"),
+      JSON.stringify({ type: "module" }),
+    );
+    await mkdir(path.join(fixture, "shell"));
+    await writeFile(
+      path.join(fixture, "shell", "index.js"),
+      "export const marker = true;\n",
+    );
+    const entry = pathToFileURL(path.join(fixture, "index.mjs")).href;
+    await writeFile(
+      path.join(fixture, "index.mjs"),
+      `export * from ${JSON.stringify(shellReexport?.[1])};\n`,
+    );
+
+    const result = spawnSync(
+      process.execPath,
+      [
+        "--input-type=module",
+        "--eval",
+        `const { marker } = await import(${JSON.stringify(entry)}); if (!marker) process.exitCode = 1;`,
+      ],
+      { encoding: "utf8" },
+    );
+
+    expect(result.status, result.stderr).toBe(0);
+  } finally {
+    await rm(fixture, { recursive: true, force: true });
+  }
+});