avtc-pi-settings-ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 avtc <tarasenkov@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# avtc-pi-settings-ui
+
+A schema-driven settings UI for [pi](https://pi.dev) extensions — define your settings, get a tabbed modal, a `/<name>:settings` command, persistence, and presets.
+
+## Features
+
+- **Schema-driven UI** — define settings once in a typed schema; the library renders the full modal automatically
+- **Tabbed layout** — group settings into tabs; each tab renders as a separate panel
+- **Typed setting items** — 7 built-in types (`string`, `number`, `duration`, `compact-threshold`, `boolean`, `model`, `thinking-level`) with presets, optional `min`/`max` bounds, and custom type support
+- **Filter-first UI** — type to filter every list by substring (over label + value); `Tab`/`Shift+Tab` switch tabs, `Enter` opens the value picker
+- **Layered persistence** — choose any combination of three storage levels via `storageLevels` (`session`, `project`, `global`); see [Persistence & session lifecycle](#persistence--session-lifecycle)
+- **Atomic writes** — settings are saved atomically to prevent corruption
+- **Value normalization** — every value is validated against the schema before it's saved
+- **Environment variable propagation** — settings can be propagated to child processes via env vars (e.g. for subagents)
+
+The rendered modal — tabbed panels, filter-first lists, and per-type value pickers:
+
+![settings modal](assets/images/settings.png)
+
+![settings dropdown](assets/images/settings-dropdown.png)
+
+## Installation
+
+Add it as a dependency of your extension:
+
+```bash
+npm install avtc-pi-settings-ui
+```
+
+### Dialog coordination (optional)
+
+The settings modal queues behind other open dialogs (instead of stealing keyboard focus) via [`avtc-pi-ui-components`](https://github.com/avtc/avtc-pi-ui-components)'s dialog coordinator. If you want that coordination, also install ui-components and load it as a companion extension:
+
+```jsonc
+// your package.json
+{
+  "dependencies": {
+    "avtc-pi-settings-ui": "^1.0.0",
+    "avtc-pi-ui-components": "^1.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "node_modules/avtc-pi-ui-components/index.ts"
+    ],
+    "allowedCodeDeps": ["avtc-pi-settings-ui"]  // ui-components is loaded, not imported
+  }
+}
+```
+
+Without ui-components the settings modal still works — it just opens immediately rather than queuing.
+
+## Public API
+
+| Export | Purpose |
+|---|---|
+| `registerSettingsCommand(pi, schema, opts)` | Register the `/<name>:settings` command + modal; returns the settings handle you read from at runtime |
+| `settingsFilePaths(name)` | Global + project file paths for `<name>`'s settings — `~/.pi/agent/<name>-settings.json` and `<cwd>/.pi/<name>-settings.json` (spread into the schema) |
+| `SettingSchema`, `SettingsSchema` | Define your settings and tabs |
+| `StorageLevel`, `SettingsHandle`, `RegisterSettingsOptions` | Types: storage levels (`session`/`project`/`global`), the returned handle, the options bag |
+| `PresetsSource`, `PresetPair`, `PresetElement`, `PresetValue` | Author `presets`: full pairs or bare values (string/number/boolean/null) |
+| `registerTypeDefinition`, `TypeDefinition`, `TypeContext` | Register custom types (7 built-ins ship pre-registered) |
+| `formatHumanDuration` | Human form of a duration |
+
+## Usage
+
+```ts
+import { registerSettingsCommand, SettingsSchema, settingsFilePaths } from "avtc-pi-settings-ui";
+
+const schema: SettingsSchema = {
+  settings: [
+    {
+      id: "mySetting",
+      label: "My Setting",
+      description: "Controls something important",
+      type: "string",
+      defaultValue: "default",
+      presets: [
+        ["Default", "default"],
+        ["Alternative", "alternative"],
+      ],
+    },
+  ],
+  tabs: [{ label: "General", settingIds: ["mySetting"] }],
+  ...settingsFilePaths("my-extension"),
+};
+
+const settings = registerSettingsCommand(pi, schema, {
+  commandName: "my-extension:settings",
+  title: "My Extension Settings",
+  titleRight: "avtc-pi-my-extension",
+  storageLevels: ["session", "project", "global"],
+  envVar: "PI_SETTINGS_MY_EXT",
+});
+
+settings.getSettings();
+```
+
+## Setting types
+
+Every setting has a `type` resolved through a first-class `TypeDefinition` registry. Seven built-ins ship out of the box:
+
+| Type | Stored value | Notes |
+|------|-------------|-------|
+| `string` | `string` | Text; closed enums via presets (`["a", "b"]`) |
+| `number` | `number` \| `null` | Optional `min`/`max` bounds; `null` (unbounded/off) via a null preset |
+| `duration` | `number` \| `null` | Human-readable (`5m`, `1h`, `30s`, `14d`); stored as milliseconds. `null` = unbounded/off, via a null preset |
+| `compact-threshold` | `string` | Compact-context thresholds (`none`, `compact`, `compact>75K`, …) |
+| `boolean` | `boolean` | `true`/`false`; presets `[true, false]` |
+| `model` | `string` \| `null` | Model id (`provider/id`); presets generated from the available models. Nullable via a `["Default", null]` preset |
+| `thinking-level` | `string` | Thinking level (label equals value) |
+
+A `presets` array can hold full `[label, value]` pairs or bare values (`"a"`, `5`, `true`, `null`); a bare value pairs with itself, except a duration string which parses to milliseconds.
+
+**Custom types:** register your own via `registerTypeDefinition(def)` and reference it as `type: "<def.id>"`. A `TypeDefinition` declares how values parse/format and optional `presets`; null support comes from including a null-valued preset (e.g. `["Off", null]`).
+
+## Persistence & session lifecycle
+
+Choose your storage levels via `storageLevels` on `registerSettingsCommand` (default: all three):
+
+- **`session`** — in-memory only; survives `/reload` (same process) but not a full restart or new terminal. When `session` is included, settings are also propagated to subagents via the env var.
+- **`project`** — `<cwd>/.pi/<name>-settings.json`. Survives across processes in that project.
+- **`global`** — `~/.pi/agent/<name>-settings.json`. Survives everywhere.
+
+**How edits save:** with a single file level (`global` or `project`), each edit writes straight to that file, so every pi instance reads the same on-disk truth. With multiple levels (or `session`), edits are held as a draft until you press a save key — `Ctrl+S` saves project, `Ctrl+D` saves global (each only when its level is enabled).
+
+> Developed with [Z.ai](https://z.ai/subscribe?ic=N5IV4LLOOV) — get 10% off your subscription via this referral link.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+// Minimal public API. Everything else (the settings handle factory, normalization internals,
+// persistence helpers, UI components, display/coerce helpers, built-in type-def knobs) is
+// internal — import it from its `src/` path only if you have a specific reason not covered here.
+
+// Persistence — the standard global/project file-path pair every consumer spreads into its schema.
+export { settingsFilePaths } from "./src/persistence.js";
+// Authoring types — the schema a consumer writes.
+export type {
+  PresetElement,
+  PresetPair,
+  PresetsSource,
+  PresetValue,
+  SettingSchema,
+  SettingsSchema,
+  SettingsTabSchema,
+  StorageLevel,
+} from "./src/schema.js";
+export type { TypeContext, TypeDefinition } from "./src/type-definitions.js";
+// Type system — register a custom TypeDefinition (the built-in 7 are pre-registered).
+export { registerTypeDefinition } from "./src/type-definitions.js";
+export type { RegisterSettingsOptions, SettingsHandle } from "./src/ui/settings-command.js";
+// Command registration — the single entry point: registers the /<name> command + modal and
+// returns the settings handle (what you call getSettings/updateSetting on at runtime).
+export { registerSettingsCommand } from "./src/ui/settings-command.js";
+
+// Display helper — the human form of a duration (the inverse of the `duration` type's parse).
+export { formatHumanDuration } from "./src/validation.js";

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "avtc-pi-settings-ui",
+  "version": "1.0.0",
+  "description": "Schema-driven settings infrastructure for pi extensions",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "index.ts",
+  "keywords": [
+    "pi-package"
+  ],
+  "scripts": {
+    "lint": "biome check .",
+    "lint:optional-params": "node scripts/no-optional-params.cjs src/ tests/",
+    "lint:bare-literals": "node scripts/no-bare-literals.cjs src/ index.ts",
+    "lint:design-refs": "node scripts/no-design-refs.cjs src/ index.ts README.md",
+    "lint:bundled-imports": "node scripts/no-bundled-extension-imports.cjs src/ index.ts",
+    "knip": "knip --production",
+    "typecheck": "tsc --noEmit --incremental --tsBuildInfoFile node_modules/.cache/tsc.tsbuildinfo",
+    "test:unit": "node scripts/test-low-priority.cjs vitest run",
+    "test:watch": "node scripts/test-low-priority.cjs vitest",
+    "test": "node scripts/test-low-priority.cjs \"node scripts/run-parallel.cjs \"npm run lint:optional-params :: npm run lint:bare-literals :: npm run lint:design-refs :: npm run lint:bundled-imports :: npm run lint:as-never :: npm run lint :: npm run typecheck :: npm run knip :: npm run dupes\" && vitest run\"",
+    "dupes": "jscpd src/ --exit-code --threshold 0.01",
+    "lint:as-never": "node scripts/no-as-never.cjs src/ tests/ index.ts"
+  },
+  "dependencies": {
+    "avtc-pi-logger": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "minimatch": "^10.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "@types/node": "^25.9.3",
+    "jscpd": "^5.0.10",
+    "knip": "^6.17.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "pi": {
+    "allowedCodeDeps": [
+      "avtc-pi-logger"
+    ]
+  },
+  "author": "avtc <tarasenkov@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/avtc/avtc-pi-settings-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/avtc/avtc-pi-settings-ui/issues"
+  },
+  "homepage": "https://github.com/avtc/avtc-pi-settings-ui",
+  "files": [
+    "index.ts",
+    "src/",
+    "assets/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/ctx-store.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Captured command context, stashed at modal-open so resolvers that run later (the model
+ * type-def's preset resolver) can read the host's model registry without it being threaded
+ * through every call. Captured once per open; tolerant of hosts that expose only a subset.
+ */
+
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+interface CapturedCtx {
+  modelRegistry?: ModelRegistry;
+  cwd?: string;
+}
+
+let captured: CapturedCtx = {};
+
+/**
+ * Stash the command context (modelRegistry + cwd) for later resolver use.
+ * Tolerates a context lacking either field — a host that does not expose modelRegistry
+ * stores `undefined`, and the model resolver degrades to a Default-only list.
+ */
+export function captureCtx(ctx: { modelRegistry?: ModelRegistry; cwd?: string }): void {
+  captured = { modelRegistry: ctx.modelRegistry, cwd: ctx.cwd };
+}
+
+/**
+ * Read the stash captured at modal-open. Resolvers (the model type-def) call this to reach
+ * the host's model registry without it being threaded through every call.
+ */
+export function getCapturedCtx(): CapturedCtx {
+  return captured;
+}

package/src/custom-validation.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Custom-value validation for the settings value-picker.
+ *
+ * These functions sit ABOVE the `TypeDefinition` registry (they look a type up and run its
+ * parse/format), so they live in their own module to keep the dependency graph acyclic:
+ * `custom-validation → type-definitions → validation` (primitives). The parse/format PRIMITIVES
+ * (`parseHumanDuration`, `formatHumanDuration`, …) stay in `validation.ts`.
+ */
+
+import type { SettingType } from "./schema.js";
+import { getTypeDefinition, type TypeContext } from "./type-definitions.js";
+
+/** Validate a custom value for a given setting type via the TypeDefinition registry.
+ *  parse(input, ctx) → undefined? invalid; non-finite? invalid; bounded && out-of-[min,max]?
+ *  invalid; else format(parsed). Returns the formatted internal value string, or undefined for invalid
+ *  (undefined, never null). `ctx` (presets/min/max) is required — pass `null` to skip
+ *  preset-matching and bounds (the value-picker always builds a real ctx from its presets). */
+export function validateCustomValue(
+  value: string,
+  settingType: SettingType,
+  ctx: TypeContext | null,
+): string | undefined {
+  const typeDef = getTypeDefinition(settingType);
+  const parsed = typeDef.parse(value.trim(), ctx ?? { presets: [] });
+  if (parsed === undefined) return undefined;
+  // Finite check: reject Infinity/NaN so the resolver's accept-criteria stays a subset
+  // of the gate's (the gate rejects non-finite via !Number.isFinite). The duration parser's bare-ms
+  // fallback would otherwise let "Infinity" through (Number("Infinity")=Infinity).
+  if (typeDef.valueType === "number" && typeof parsed === "number" && !Number.isFinite(parsed)) {
+    return undefined;
+  }
+  if (typeDef.bounded === true && typeof parsed === "number" && ctx !== null) {
+    if (ctx.min !== undefined && parsed < ctx.min) return undefined;
+    if (ctx.max !== undefined && parsed > ctx.max) return undefined;
+  }
+  return typeDef.format(parsed, ctx ?? { presets: [] });
+}
+
+/** Setting types that accept genuinely meaningful free-form custom input (a TypeDefinition field lookup). */
+export function supportsCustomValues(settingType: SettingType): boolean {
+  return getTypeDefinition(settingType).supportsCustomValues;
+}

package/src/factory.ts

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Factory for creating settings extensions.
+ *
+ * Given a SettingsSchema + options, provides getSettings / updateSetting / loadSettingsIntoMemory.
+ * Two persistence modes, selected by `storageLevels`:
+ *  - STATELESS (a single file level — `["global"]` or `["project"]`): `getSettings` reads the file
+ *    fresh on every call (cross-instance immediate), `updateSetting` does an immediate
+ *    read-modify-write of that file, and the env var is never read or written.
+ *  - BUFFER (everything else — the default session+project+global, or any combination involving
+ *    session or multiple files): an in-memory buffer is the read target; the env var is serialized
+ *    iff `session` is included (for subagent propagation + reload survival).
+ */
+
+import {
+  clampSettings,
+  isInvalidResult,
+  normalizeFromSchema,
+  resolveSettingValue,
+  validateSchema,
+} from "./normalization.js";
+import {
+  saveGlobalSettings as _saveGlobalSettings,
+  saveProjectSettings as _saveProjectSettings,
+  atomicWriteJson,
+  loadSettingsFromFiles,
+  readJsonFile,
+} from "./persistence.js";
+import { normalizeStorageLevels, type SettingSchema, type SettingsSchema, type StorageLevel } from "./schema.js";
+
+/** Resolve a raw value through the gate, returning the default for the `undefined` reset sentinel. */
+function resolveUpdateValue(
+  raw: unknown,
+  setting: SettingSchema,
+): { value: unknown; invalid: false } | { invalid: true } {
+  if (raw === undefined) return { value: setting.defaultValue, invalid: false };
+  const resolved = resolveSettingValue({ [setting.id]: raw }, setting);
+  if (isInvalidResult(resolved)) return { invalid: true };
+  return { value: resolved, invalid: false };
+}
+
+/**
+ * Create a settings extension from a schema.
+ *
+ * The host extension registers the command via `registerSettingsCommand` (which auto-calls
+ * `loadSettingsIntoMemory` at registration + on `session_start`), so consumers no longer wire
+ * startup loading by hand.
+ */
+export function createSettingsExtension<S extends object = Record<string, unknown>>(
+  schema: SettingsSchema,
+  options: {
+    storageLevels?: StorageLevel[];
+    clampFn?: (result: Record<string, unknown>) => void;
+    envVar?: string;
+    onLoad?: () => void;
+  } = {},
+) {
+  // Validate the schema up front (fail-fast): preset strings parse, every setting is in a tab,
+  // every tab id resolves, no duplicate/orphan ids. Also eagerly populates the static-presets
+  // cache so runtime resolution never re-throws.
+  validateSchema(schema);
+
+  const clampFn = options.clampFn;
+  const envVar = options.envVar;
+  const onLoad = options.onLoad;
+  const storageLevels = normalizeStorageLevels(options.storageLevels);
+  const sessionIncluded = storageLevels.includes("session");
+  const singleFileLevel =
+    storageLevels.length === 1 && (storageLevels[0] === "global" || storageLevels[0] === "project");
+  const singleFileKind: "global" | "project" | null = singleFileLevel
+    ? (storageLevels[0] as "global" | "project")
+    : null;
+
+  // Buffer-mode state (unused in stateless mode — every read/write hits the file directly).
+  let settings: Record<string, unknown> = {};
+  let settingsLoaded = false;
+  // cwd/globalDir learned via loadSettingsIntoMemory (used by stateless reads + project writes).
+  // Default to process.cwd() so a stateless getSettings() works before any load call.
+  let cwd = process.cwd();
+  let globalDir: string | undefined;
+
+  function computeDefaults(): S {
+    const defaults: Record<string, unknown> = {};
+    for (const setting of schema.settings) {
+      defaults[setting.id] = setting.defaultValue;
+    }
+    return defaults as S;
+  }
+
+  /** The single file path for a stateless handle (global or project, per `singleFileKind`). */
+  function singleFilePath(): string {
+    return singleFileKind === "global" ? schema.globalPath(globalDir) : schema.projectPath(cwd);
+  }
+
+  function getSettings(): S {
+    if (singleFileLevel) {
+      // Stateless: read the file fresh every call (cross-instance immediate), normalize + clamp.
+      const raw = readJsonFile(singleFilePath()) ?? {};
+      const normalized = normalizeFromSchema(raw, schema);
+      clampSettings(normalized, clampFn);
+      return normalized as S;
+    }
+    return settings as S;
+  }
+
+  /** Apply a resolved value to the buffer + clamp + serialize the env var (buffer mode only). */
+  function applyToBuffer(canonicalKey: string, resolvedValue: unknown): void {
+    settings[canonicalKey] = resolvedValue;
+    settingsLoaded = true;
+    clampSettings(settings, clampFn);
+    if (envVar && sessionIncluded) {
+      process.env[envVar] = JSON.stringify(settings);
+    }
+  }
+
+  /**
+   * Read-modify-write a single key into a file: read the fresh file, set the key, normalize +
+   * clamp the whole record, full-rewrite atomically. Used by both stateless no-level writes and
+   * explicit project/global surgical writes.
+   */
+  function writeKeyToFile(path: string, canonicalKey: string, resolvedValue: unknown): void {
+    const existing = readJsonFile(path) ?? {};
+    existing[canonicalKey] = resolvedValue;
+    const normalized = normalizeFromSchema(existing, schema);
+    clampSettings(normalized, clampFn);
+    atomicWriteJson(path, normalized);
+  }
+
+  function updateSetting(
+    key: string,
+    value: unknown,
+    opts: {
+      level?: StorageLevel;
+    } = {},
+  ): void {
+    const settingSchema = schema.settings.find((s) => s.id === key || s.aliases?.includes(key));
+    if (!settingSchema) return;
+    const canonicalKey = settingSchema.id;
+    const level = opts?.level;
+
+    // Route the value through the same gate as load. INVALID → no write (keep the old value).
+    const resolved = resolveUpdateValue(value, settingSchema);
+    if (resolved.invalid) return;
+
+    if (level === "session") {
+      // Buffer only — no file write. (Only meaningful in buffer mode.)
+      applyToBuffer(canonicalKey, resolved.value);
+      return;
+    }
+
+    if (level === "project" || level === "global") {
+      // Explicit surgical one-key write to that file (preserves other keys), + sync the buffer in
+      // buffer mode so a subsequent getSettings() reflects it.
+      const path = level === "global" ? schema.globalPath(globalDir) : schema.projectPath(cwd);
+      writeKeyToFile(path, canonicalKey, resolved.value);
+      if (!singleFileLevel) applyToBuffer(canonicalKey, resolved.value);
+      return;
+    }
+
+    // No level → mode-aware.
+    if (singleFileLevel) {
+      // Immediate read-modify-write of the single file. Stateless: no buffer, no env var.
+      writeKeyToFile(singleFilePath(), canonicalKey, resolved.value);
+    } else {
+      // Buffer: update the buffer + clamp + env var (iff session is included).
+      applyToBuffer(canonicalKey, resolved.value);
+    }
+  }
+
+  function loadSettingsIntoMemory(cwdArg: string | undefined, globalDirArg: string | undefined): void {
+    cwd = cwdArg ?? process.cwd();
+    globalDir = globalDirArg;
+
+    // Stateless: nothing to buffer (every read hits the file). Just fire the load hook.
+    if (singleFileLevel) {
+      onLoad?.();
+      return;
+    }
+
+    try {
+      // Env var first (subagent propagation + reload survival) — only when session is included.
+      if (envVar && sessionIncluded) {
+        const envSettings = process.env[envVar];
+        if (envSettings) {
+          const raw = JSON.parse(envSettings) as Record<string, unknown>;
+          const parsed: Record<string, unknown> = Object.create(null);
+          for (const key of Object.keys(raw)) parsed[key] = raw[key]; // Prevent prototype pollution
+          settings = normalizeFromSchema(parsed, schema);
+          clampSettings(settings, clampFn);
+          settingsLoaded = true;
+        }
+      }
+
+      if (!settingsLoaded) {
+        const defaults = computeDefaults();
+        settings = loadSettingsFromFiles(cwd, schema, defaults as unknown as Record<string, unknown>, globalDir);
+        clampSettings(settings, clampFn);
+        settingsLoaded = true;
+      }
+    } catch {
+      settings = computeDefaults() as unknown as Record<string, unknown>;
+      settingsLoaded = true;
+    } finally {
+      if (envVar && sessionIncluded) {
+        process.env[envVar] = JSON.stringify(settings);
+      }
+      onLoad?.();
+    }
+  }
+
+  function saveGlobalSettings(saveSettings: Record<string, unknown>, globalDirArg: string | undefined): void {
+    if (globalDirArg !== undefined) globalDir = globalDirArg;
+    _saveGlobalSettings(saveSettings, schema, globalDir);
+  }
+
+  function saveProjectSettings(saveSettings: Record<string, unknown>, cwdArg: string): void {
+    cwd = cwdArg;
+    _saveProjectSettings(saveSettings, cwd, schema);
+  }
+
+  return {
+    getSettings,
+    updateSetting,
+    loadSettingsIntoMemory,
+    saveGlobalSettings,
+    saveProjectSettings,
+    computeDefaults,
+    schema,
+    storageLevels,
+  };
+}

package/src/model-presets.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * The model presets resolver — the default `presets` source for the `model` type-def. Reads the
+ * host's model registry (captured at modal-open), keeps only the enabled models, and returns the
+ * `[label, value]` pairs the picker renders. Resolved once at open (by `resolveFunctionPresets`),
+ * so the list reflects the live models.json / auth state on each open.
+ *
+ * Value shape: `"<provider>/<id>"` (the form pi's own model selector pushes), with a leading
+ * `["Default", null]` pair so a model setting can be unset. Labels mirror pi's selector:
+ * `"<id> [<provider>]"`.
+ */
+
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { minimatch } from "minimatch";
+import { getCapturedCtx } from "./ctx-store.js";
+import { readJsonFile } from "./persistence.js";
+import type { PresetPair } from "./schema.js";
+
+/** The model fields `modelLabel` reads. Structural so any model-like object works. */
+interface ModelLike {
+  readonly id: string;
+  readonly provider: string;
+}
+
+/** The null entry — a model setting is always selectable as "Default" (unset). */
+const DEFAULT_PAIR: PresetPair = ["Default", null];
+
+/**
+ * Format a model as `"<id> [<provider>]"` — the same shape pi's own model selector renders (the
+ * provider sits in a muted badge there; the raw provider id is used, not a display name).
+ */
+export function modelLabel(model: ModelLike): string {
+  return `${model.id} [${model.provider}]`;
+}
+
+/** The serialized value for a model: `"<provider>/<id>"` (pi's full-id form). */
+function modelValue(model: ModelLike): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/** Split a serialized model value `"<provider>/<id>"` on the FIRST slash, so an id that itself
+ *  contains a slash still resolves by its leading provider/id segments. Returns `null` when the
+ *  value has no slash (not a `provider/id` form — e.g. the null/"Default" entry). */
+export function splitModelId(value: string): { provider: string; id: string } | null {
+  const slash = value.indexOf("/");
+  if (slash < 0) return null;
+  return { provider: value.slice(0, slash), id: value.slice(slash + 1) };
+}
+
+/**
+ * Read the host's enabled-models patterns from its settings file. Returns `null` when the file is
+ * absent or carries no `enabledModels` (meaning "no scoping — all available models"). Exposed as a
+ * seam so the resolver can be unit-tested without touching the real settings path.
+ */
+export function readEnabledModelPatterns(): string[] | null {
+  const raw = readJsonFile(join(getAgentDir(), "settings.json"));
+  const patterns = raw?.enabledModels;
+  return Array.isArray(patterns) ? patterns : null;
+}
+
+/**
+ * Keep a model iff any enabled-models pattern matches it — either its full `provider/id` or its
+ * bare `id`. Matching is case-insensitive (pi resolves scopes nocase). A pattern without glob
+ * metacharacters matches as a literal under minimatch, so a full id like `anthropic/claude-3-5`
+ * matches exactly the same way a glob like `anthropic/*` does.
+ *
+ * Two deviations from pi's own resolver: a non-glob partial name (e.g. `claude`) does not get
+ * fuzzy-matched against model display names, and a trailing `:thinkingLevel` suffix on a pattern
+ * is not stripped (thinking levels are ignored here).
+ */
+function isEnabled(model: ModelLike, patterns: readonly string[]): boolean {
+  const fullId = modelValue(model);
+  return patterns.some(
+    (pattern) => minimatch(fullId, pattern, { nocase: true }) || minimatch(model.id, pattern, { nocase: true }),
+  );
+}
+
+/**
+ * Resolve the model presets: the captured registry's available models, scoped by the host's
+ * enabled-models patterns, each `[modelLabel(model), "provider/id"]`, with `["Default", null]`
+ * prepended. When the registry was not captured, or enabled-models patterns are configured but
+ * match nothing, the list degrades to `["Default", null]` (the modal still opens).
+ */
+export function resolveModelPresets(): PresetPair[] {
+  const { modelRegistry } = getCapturedCtx();
+  if (!modelRegistry) return [DEFAULT_PAIR];
+
+  modelRegistry.refresh();
+  const all = modelRegistry.getAvailable();
+  const patterns = readEnabledModelPatterns();
+
+  // null/absent enabledModels → no scoping (all available). Non-null but matching nothing → also
+  // fall back to all (a stale/typo pattern should not empty the picker).
+  const scoped = patterns === null ? all : all.filter((m) => isEnabled(m, patterns));
+  const effective = scoped.length > 0 ? scoped : all;
+
+  return [DEFAULT_PAIR, ...effective.map((m): PresetPair => [modelLabel(m), modelValue(m)])];
+}