dsh-plugin-subscription-usage 0.0.0-stage → 0.1.0

package/lib/json-text.d.ts

@@ -0,0 +1,2 @@
+/** Read plugin-owned JSON saved with or without a leading UTF-8 byte order mark. */
+export declare function parseJsonText(text: string): unknown;

package/lib/json-text.js

@@ -0,0 +1,4 @@
+/** Read plugin-owned JSON saved with or without a leading UTF-8 byte order mark. */
+export function parseJsonText(text) {
+    return JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+}

package/lib/model-defaults.d.ts

@@ -0,0 +1,23 @@
+import { type ProviderId } from './auth/store.js';
+/** One model id → its configured default reasoning effort id. */
+export type ModelDefaultMap = Readonly<Record<string, string>>;
+/** Provider route → model defaults. */
+export type ModelDefaults = Readonly<Partial<Record<ProviderId, ModelDefaultMap>>>;
+/** Absolute path of the defaults file. */
+export declare function modelDefaultsFilePath(): string;
+/**
+ * The last load failure, or a warning about entries that were skipped while
+ * loading; consumers only use it for diagnostics.
+ */
+export declare function modelDefaultsLoadError(): unknown;
+/** A detached snapshot for the RPC surface (render + diffing). */
+export declare function modelDefaultsSnapshot(): ModelDefaults;
+/**
+ * Set or clear one model's configured default effort, then persist. The
+ * memory snapshot updates only after the atomic write succeeds, so a failed
+ * write never leaves the live state ahead of the file.
+ * @param provider - the subscription provider route.
+ * @param model - the wire model id.
+ * @param effort - the effort id, or undefined to clear the override.
+ */
+export declare function setDefaultEffort(provider: ProviderId, model: string, effort: string | undefined): Promise<void>;

package/lib/model-defaults.js

@@ -0,0 +1,238 @@
+/**
+ * Per-model default reasoning effort overrides — the durable half of the
+ * Settings page's per-model "default effort" pickers.
+ *
+ * The file lives at `~/.dsh/plugins/subscriptions/model-defaults.json`
+ * (mode 0600, atomic replace). Shape: `{ "<provider>": { "<model id>": "<effort>" } }`.
+ * An absent entry means "follow the provider's own default": the `Default`
+ * chip the model picker shows when the discovered catalog advertises no
+ * default at all.
+ *
+ * Writes are single-process and atomic, but *not* as serialised as the rest
+ * of the page: the Settings page disables only the row being saved, so two
+ * rows saved back to back can overlap. The write chain below serialises them,
+ * so no update is lost to a read-modify-write race. Every read comes from the
+ * in-memory snapshot, so the on-disk file only needs to survive a restart: a
+ * malformed file reads as empty and is rewritten on the next save, never
+ * taking the plugin down with it.
+ */
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { PROVIDER_IDS } from './auth/store.js';
+import { parseJsonText } from './json-text.js';
+/** Absolute path of the defaults file. */
+export function modelDefaultsFilePath() {
+    return dshHomePath('plugins', 'subscriptions', 'model-defaults.json');
+}
+const EMPTY = Object.freeze({});
+/** In-memory snapshot read by every consumer (adapters, RPC). */
+let current = EMPTY;
+/** One lazy load of the on-disk file (read once per process). */
+let ready;
+/** Last load failure, surfaced to callers that care; defaults stay empty. */
+let loadError;
+/**
+ * Serialises every write: the read-modify-write sequence must not interleave,
+ * or a fast second save would compute its snapshot from the stale `current`
+ * and silently drop the first update (the UI disables only the row being
+ * saved, so overlaps are reachable).
+ */
+let writeChain = Promise.resolve();
+/**
+ * Validate one persisted provider section: a string→string map, or undefined.
+ * Malformed *entries* are skipped, not the whole section: one bad value (a
+ * hand edit losing its quotes) must not silently un-configure every model in
+ * that provider. What was dropped is reported so the caller can surface it
+ * instead of the loss disappearing.
+ */
+function sanitizeProvider(value, dropped) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const entries = {};
+    for (const [model, effort] of Object.entries(value)) {
+        if (typeof effort !== 'string' || effort.length === 0) {
+            dropped.push(model);
+            continue;
+        }
+        entries[model] = effort;
+    }
+    if (Object.keys(entries).length === 0)
+        return undefined;
+    return Object.freeze(entries);
+}
+/** Validate the raw document: only known providers, malformed sections dropped. */
+function sanitizeDefaults(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { defaults: EMPTY, dropped: [] };
+    const record = value;
+    const result = {};
+    const dropped = [];
+    for (const provider of PROVIDER_IDS) {
+        const section = sanitizeProvider(record[provider], dropped);
+        if (section !== undefined)
+            result[provider] = section;
+    }
+    return { defaults: Object.freeze(result), dropped };
+}
+/** Read and validate the on-disk file; a missing file reads as empty. */
+async function loadFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return EMPTY;
+        throw error;
+    }
+    try {
+        const { defaults, dropped } = sanitizeDefaults(parseJsonText(text));
+        if (dropped.length > 0)
+            loadError = new Error(`subscriptions model defaults: ${dropped.length} malformed entr${dropped.length === 1 ? 'y' : 'ies'} skipped (${dropped.join(', ')}); fix or delete the file`);
+        return defaults;
+    }
+    catch {
+        throw new Error(`subscriptions model defaults at ${path} are not valid JSON; fix or delete the file`);
+    }
+}
+/** Resolve the module state once from disk; failures leave the defaults empty. */
+async function ensureReady() {
+    ready ??= loadFile(modelDefaultsFilePath()).then((loaded) => {
+        current = loaded;
+        // loadFile itself sets loadError for skipped entries; do not clobber it.
+    }, (error) => {
+        loadError = error;
+        current = EMPTY;
+    });
+    return ready;
+}
+/** Persist a snapshot atomically with owner-only permissions. */
+async function atomicPersist(defaults, path) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await writeFile(tmp, JSON.stringify(defaults, null, 2), { mode: 0o600 });
+        await chmod(tmp, 0o600);
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+let persistDefaults = atomicPersist;
+/**
+ * Clone one provider section, or undefined when nothing is configured for it.
+ * The clone is prototype-less: model ids are provider-supplied catalog data
+ * used as object keys, and consumers index the section directly (the RPC
+ * catalog in index.ts does), so an id like `toString` would otherwise yield an
+ * inherited *function* where a string is declared.
+ */
+function sectionOf(defaults, provider) {
+    const section = defaults[provider];
+    if (section === undefined)
+        return undefined;
+    return Object.assign(Object.create(null), section);
+}
+/**
+ * Ready the defaults store.
+ * @internal Exported for tests; index.ts calls it at apply time so every
+ * later synchronous read sees the persisted state.
+ */
+export async function loadModelDefaults() {
+    await ensureReady();
+}
+/**
+ * The last load failure, or a warning about entries that were skipped while
+ * loading; consumers only use it for diagnostics.
+ */
+export function modelDefaultsLoadError() {
+    return loadError;
+}
+/**
+ * The configured default effort for one model, or undefined when none (the
+ * picker then follows the provider's own default).
+ * @internal Exported for the adapters' `defaultEffortOf` options.
+ */
+export function defaultEffortOf(provider, model) {
+    const section = current[provider];
+    if (section === undefined)
+        return undefined;
+    // Own-property lookup: a model id is provider-supplied catalog data, and a
+    // plain index would inherit from Object.prototype for names like
+    // `toString`, handing a *function* to mergeReasoning (which then throws and
+    // breaks that model's resolution).
+    return Object.prototype.hasOwnProperty.call(section, model) ? section[model] : undefined;
+}
+/** A detached snapshot for the RPC surface (render + diffing). */
+export function modelDefaultsSnapshot() {
+    const result = {};
+    for (const provider of PROVIDER_IDS) {
+        const section = sectionOf(current, provider);
+        if (section !== undefined)
+            result[provider] = section;
+    }
+    return Object.freeze(result);
+}
+/**
+ * Set or clear one model's configured default effort, then persist. The
+ * memory snapshot updates only after the atomic write succeeds, so a failed
+ * write never leaves the live state ahead of the file.
+ * @param provider - the subscription provider route.
+ * @param model - the wire model id.
+ * @param effort - the effort id, or undefined to clear the override.
+ */
+export function setDefaultEffort(provider, model, effort) {
+    // Chained behind every earlier write: the snapshot `current` is read inside
+    // the chain, so two overlapping saves cannot lose either update. The caller
+    // receives the promise of its own write (a rejection propagates), not the
+    // shared chain.
+    const run = writeChain.then(async () => {
+        await ensureReady();
+        const section = { ...sectionOf(current, provider) ?? {} };
+        if (effort === undefined) {
+            delete section[model];
+        }
+        else {
+            section[model] = effort;
+        }
+        const next = { ...current };
+        if (Object.keys(section).length === 0) {
+            delete next[provider];
+        }
+        else {
+            next[provider] = Object.freeze(section);
+        }
+        const frozen = Object.freeze(next);
+        await persistDefaults(frozen, modelDefaultsFilePath());
+        current = frozen;
+    });
+    // Keep the chain alive even when one write fails, or every later save would
+    // be stuck behind the rejected promise. The caller has already received the
+    // rejection through `run`.
+    writeChain = run.catch(() => undefined);
+    return run;
+}
+/**
+ * Drop the in-memory state and the cached load. Test-only: lets a suite
+ * unwind the lazy singleton before the next `loadModelDefaults`.
+ * @internal Exported for tests only; not part of the plugin's public surface.
+ */
+export async function resetModelDefaultsForTests() {
+    current = EMPTY;
+    ready = undefined;
+    loadError = undefined;
+    writeChain = Promise.resolve();
+    persistDefaults = atomicPersist;
+}
+/**
+ * Test-only seam: replace the atomic persistence so a failure happens on the
+ * real write path. Proves a failed write propagates to the caller and does
+ * not wedge the write chain (resetModelDefaultsForTests restores the real
+ * implementation).
+ * @internal Exported for tests only.
+ */
+export function overridePersistForTests(persist) {
+    persistDefaults = persist;
+}

package/lib/model-speeds.d.ts

@@ -0,0 +1,10 @@
+import type { SpeedTier } from './auth/rpc.js';
+/** Per-model composer preferences; publish changes only after the atomic save. */
+export declare class ModelSpeeds {
+    private readonly path;
+    private current;
+    private writes;
+    constructor(path?: string);
+    get(model: string): SpeedTier | undefined;
+    set(model: string, tier: SpeedTier): Promise<void>;
+}

package/lib/model-speeds.js

@@ -0,0 +1,48 @@
+/** Durable composer speed choices, separate from Settings-page subagent defaults. */
+import { readFileSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+/** Per-model composer preferences; publish changes only after the atomic save. */
+export class ModelSpeeds {
+    path;
+    current = new Map();
+    writes = Promise.resolve();
+    constructor(path = dshHomePath('plugins', 'subscriptions', 'model-speeds.json')) {
+        this.path = path;
+        try {
+            const raw = JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, ''));
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('expected model-to-speed map');
+            for (const [model, tier] of Object.entries(raw)) {
+                if (!model.trim() || (tier !== 'standard' && tier !== 'fast'))
+                    throw new Error('invalid model speed');
+                this.current.set(model, tier);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error(`Cannot read model speeds at ${path}`, { cause: error });
+        }
+    }
+    get(model) {
+        return this.current.get(model);
+    }
+    set(model, tier) {
+        const run = this.writes.then(async () => {
+            const next = new Map(this.current).set(model, tier);
+            await mkdir(dirname(this.path), { recursive: true });
+            const temporary = `${this.path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify(Object.fromEntries(next), null, 2), { mode: 0o600 });
+                await rename(temporary, this.path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+            this.current = next;
+        });
+        this.writes = run.catch(() => undefined);
+        return run;
+    }
+}

package/lib/models-directory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The configurable-provider entries that make each subscription a row on the
+ * DSH Models settings page. The Models page joins `llm.listConfigurableProviders`
+ * with live routes and renders our `settings.models.provider-card` slot in every
+ * row whose `settingsNs` is this plugin's entry id.
+ */
+import type { LlmConfigurableProvider } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from './auth/store.js';
+/** Row titles on the Models page. */
+export declare const PROVIDER_DISPLAY_NAMES: Record<ProviderId, string>;
+/**
+ * Directory entries for the enabled providers.
+ * @param providers - enabled provider ids in display order.
+ * @param settingsNs - this plugin's Loader entry id; the Models page dispatches the card slot by it.
+ * @returns one entry per provider, OAuth-authenticated with no API-key variables.
+ */
+export declare function directoryEntries(providers: readonly ProviderId[], settingsNs: string): LlmConfigurableProvider[];

package/lib/models-directory.js

@@ -0,0 +1,25 @@
+/** Row titles on the Models page. */
+export const PROVIDER_DISPLAY_NAMES = {
+    codex: 'ChatGPT (Codex)',
+    claude: 'Claude',
+    grok: 'Grok',
+    copilot: 'GitHub Copilot',
+    antigravity: 'Google Antigravity',
+};
+/**
+ * Directory entries for the enabled providers.
+ * @param providers - enabled provider ids in display order.
+ * @param settingsNs - this plugin's Loader entry id; the Models page dispatches the card slot by it.
+ * @returns one entry per provider, OAuth-authenticated with no API-key variables.
+ */
+export function directoryEntries(providers, settingsNs) {
+    return providers.map(provider => ({
+        provider,
+        displayName: PROVIDER_DISPLAY_NAMES[provider],
+        settingsNs,
+        // The row's settings address. An empty path marks the row configured once
+        // the namespace is described, which our volatile `usage` field ensures.
+        settingsPath: [],
+        nativeAuth: { env: [], oauth: true },
+    }));
+}

package/lib/provider-settings.d.ts

@@ -0,0 +1,55 @@
+import { type ProviderId } from './auth/store.js';
+export declare const PROVIDER_TOOLS: {
+    readonly codex: readonly ["image_generate", "web_search"];
+    readonly claude: readonly [];
+    readonly grok: readonly ["image_generate", "video_generate", "x_search"];
+    readonly copilot: readonly [];
+    readonly antigravity: readonly [];
+};
+export type SubscriptionTool = 'image_generate' | 'video_generate' | 'x_search' | 'web_search';
+/** Mirrors `PromptCacheTtl` in translate/anthropic.ts; kept here so the client bundle needs no translate import. */
+export declare const PROMPT_CACHE_TTLS: readonly ["5m", "1h"];
+export type PromptCacheTtlSetting = typeof PROMPT_CACHE_TTLS[number];
+export type SubagentSpeedTier = 'standard' | 'fast';
+export interface AccountPreferences {
+    alias?: string;
+    /** Absent means included. */
+    poolEnabled?: boolean;
+    /** Absent means no separate picker entries. */
+    independentEntry?: boolean;
+    /** Absent allows every model; [] allows none. */
+    poolModels?: string[];
+}
+export interface ProviderPreferences {
+    /** Presentation only; never used as a provider or model routing key. */
+    displayName?: string;
+    modelDisplayNames?: Record<string, string>;
+    accounts?: Record<string, AccountPreferences>;
+    /** Absent follows discovery; an explicit selection hides newly discovered models. */
+    visibleModels?: string[];
+    contextWindows?: Record<string, number>;
+    /** Codex only: per-model defaults for subagents, independent of main-session speed. */
+    subagentSpeeds?: Record<string, SubagentSpeedTier>;
+    tools?: Partial<Record<SubscriptionTool, boolean>>;
+    /** Claude only: overrides the plugin config's `claudePromptCacheTtl`; absent follows config. */
+    promptCacheTtl?: PromptCacheTtlSetting;
+}
+export declare function validatePreferences(provider: ProviderId, input: unknown): ProviderPreferences;
+/** Durable user preferences, independent of expiring discovery caches. */
+export declare class ProviderSettingsStore {
+    private current;
+    private writes;
+    readonly path: string;
+    constructor(path?: string);
+    get(provider: ProviderId): ProviderPreferences;
+    visible(provider: ProviderId, model: string): boolean;
+    modelName(provider: ProviderId, model: string, fallback: string): string;
+    contextWindow(model: string): number | undefined;
+    /** Read on every request so saved changes apply to the next subagent request. */
+    subagentSpeed(model: string): SubagentSpeedTier;
+    /** The Settings-page Claude cache TTL; undefined follows the plugin config. Read per request, so no clone. */
+    promptCacheTtl(): PromptCacheTtlSetting | undefined;
+    /** Creation-time policy survives restarts and never changes an existing session. */
+    toolEnabled(provider: ProviderId, tool: SubscriptionTool, createdAt?: number): boolean;
+    set(provider: ProviderId, input: unknown): Promise<void>;
+}

package/lib/provider-settings.js

@@ -0,0 +1,215 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { PROVIDER_IDS } from './auth/store.js';
+import { parseJsonText } from './json-text.js';
+export const PROVIDER_TOOLS = {
+    codex: ['image_generate', 'web_search'],
+    claude: [],
+    grok: ['image_generate', 'video_generate', 'x_search'],
+    copilot: [],
+    antigravity: [],
+};
+/** Mirrors `PromptCacheTtl` in translate/anthropic.ts; kept here so the client bundle needs no translate import. */
+export const PROMPT_CACHE_TTLS = ['5m', '1h'];
+export function validatePreferences(provider, input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('settings must be an object');
+    const raw = input;
+    const result = {};
+    const nameOf = (value) => {
+        if (typeof value !== 'string' || value.trim().length > 80 || /[\u0000-\u001f\u007f]/.test(value)) {
+            throw new Error('display name must be a single line of at most 80 characters');
+        }
+        return value.trim();
+    };
+    if (raw.displayName !== undefined) {
+        const name = nameOf(raw.displayName);
+        if (name)
+            result.displayName = name;
+    }
+    if (raw.modelDisplayNames !== undefined) {
+        if (!raw.modelDisplayNames || typeof raw.modelDisplayNames !== 'object' || Array.isArray(raw.modelDisplayNames)) {
+            throw new Error('modelDisplayNames must be a model-to-name map');
+        }
+        const names = Object.create(null);
+        for (const [id, value] of Object.entries(raw.modelDisplayNames)) {
+            if (!id.trim())
+                throw new Error('model display name requires a model id');
+            const name = nameOf(value);
+            if (name)
+                names[id] = name;
+        }
+        if (Object.keys(names).length)
+            result.modelDisplayNames = names;
+    }
+    if (raw.accounts !== undefined) {
+        if (!raw.accounts || typeof raw.accounts !== 'object' || Array.isArray(raw.accounts))
+            throw new Error('accounts must be an account-to-preferences map');
+        result.accounts = Object.create(null);
+        for (const [key, value] of Object.entries(raw.accounts)) {
+            if (!key.trim() || !value || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('invalid account preferences');
+            const account = value;
+            const parsed = {};
+            if (account.alias !== undefined) {
+                if (typeof account.alias !== 'string')
+                    throw new Error('account alias must be a string');
+                parsed.alias = account.alias.trim();
+            }
+            for (const field of ['poolEnabled', 'independentEntry']) {
+                if (account[field] !== undefined) {
+                    if (typeof account[field] !== 'boolean')
+                        throw new Error(`${field} must be a boolean`);
+                    parsed[field] = account[field];
+                }
+            }
+            if (account.poolModels !== undefined) {
+                if (!Array.isArray(account.poolModels) || account.poolModels.some(id => typeof id !== 'string' || !id.trim()))
+                    throw new Error('poolModels must be an array of model ids');
+                parsed.poolModels = [...new Set(account.poolModels)];
+            }
+            result.accounts[key] = parsed;
+        }
+    }
+    if (raw.visibleModels !== undefined) {
+        if (!Array.isArray(raw.visibleModels) || raw.visibleModels.some(id => typeof id !== 'string' || !id.trim())) {
+            throw new Error('visibleModels must be an array of model ids');
+        }
+        result.visibleModels = [...new Set(raw.visibleModels)];
+    }
+    if (raw.contextWindows !== undefined) {
+        if (provider !== 'codex')
+            throw new Error('context window overrides are currently supported only for Codex');
+        if (!raw.contextWindows || typeof raw.contextWindows !== 'object' || Array.isArray(raw.contextWindows)) {
+            throw new Error('contextWindows must be a model-to-token map');
+        }
+        result.contextWindows = Object.create(null);
+        for (const [model, value] of Object.entries(raw.contextWindows)) {
+            if (!model.trim() || typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+                throw new Error('context windows must be positive safe integers');
+            }
+            result.contextWindows[model] = value;
+        }
+    }
+    if (raw.promptCacheTtl !== undefined) {
+        if (provider !== 'claude')
+            throw new Error('promptCacheTtl is currently supported only for Claude');
+        if (!PROMPT_CACHE_TTLS.includes(raw.promptCacheTtl)) {
+            throw new Error(`promptCacheTtl must be one of ${PROMPT_CACHE_TTLS.join(', ')}`);
+        }
+        result.promptCacheTtl = raw.promptCacheTtl;
+    }
+    if (raw.subagentSpeeds !== undefined) {
+        if (provider !== 'codex')
+            throw new Error('subagent speeds are currently supported only for Codex');
+        if (!raw.subagentSpeeds || typeof raw.subagentSpeeds !== 'object' || Array.isArray(raw.subagentSpeeds)) {
+            throw new Error('subagent speeds must be a model-to-speed map');
+        }
+        result.subagentSpeeds = Object.create(null);
+        for (const [model, tier] of Object.entries(raw.subagentSpeeds)) {
+            if (!model.trim() || (tier !== 'standard' && tier !== 'fast')) {
+                throw new Error('subagent speeds require a model id and either "standard" or "fast"');
+            }
+            result.subagentSpeeds[model] = tier;
+        }
+    }
+    if (raw.tools !== undefined) {
+        if (!raw.tools || typeof raw.tools !== 'object' || Array.isArray(raw.tools))
+            throw new Error('tools must be an object');
+        result.tools = {};
+        for (const [tool, enabled] of Object.entries(raw.tools)) {
+            if (!PROVIDER_TOOLS[provider].includes(tool) || typeof enabled !== 'boolean') {
+                throw new Error(`unsupported tool setting: ${provider}/${tool}`);
+            }
+            result.tools[tool] = enabled;
+        }
+    }
+    return result;
+}
+/** Durable user preferences, independent of expiring discovery caches. */
+export class ProviderSettingsStore {
+    current = { providers: {}, toolHistory: [] };
+    writes = Promise.resolve();
+    path;
+    constructor(path = dshHomePath('plugins', 'subscriptions', 'provider-settings.json')) {
+        this.path = path;
+        try {
+            const raw = parseJsonText(readFileSync(path, 'utf8'));
+            if (!raw.providers || !Array.isArray(raw.toolHistory))
+                throw new Error('invalid settings document');
+            for (const provider of PROVIDER_IDS) {
+                if (Object.hasOwn(raw.providers, provider))
+                    this.current.providers[provider] = validatePreferences(provider, raw.providers[provider]);
+            }
+            this.current.toolHistory = raw.toolHistory.map(revision => {
+                if (!PROVIDER_IDS.includes(revision.provider) || !Number.isSafeInteger(revision.at) || revision.at < 0)
+                    throw new Error('invalid tool history');
+                const tools = validatePreferences(revision.provider, { tools: revision.tools }).tools ?? {};
+                return { at: revision.at, provider: revision.provider, tools };
+            }).sort((a, b) => a.at - b.at);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error(`Cannot read provider settings at ${path}`, { cause: error });
+        }
+    }
+    get(provider) {
+        return structuredClone(this.current.providers[provider] ?? {});
+    }
+    visible(provider, model) {
+        return this.current.providers[provider]?.visibleModels?.includes(model) ?? true;
+    }
+    modelName(provider, model, fallback) {
+        const names = this.current.providers[provider]?.modelDisplayNames;
+        return names && Object.hasOwn(names, model) ? names[model] : fallback;
+    }
+    contextWindow(model) {
+        const windows = this.current.providers.codex?.contextWindows;
+        return windows && Object.hasOwn(windows, model) ? windows[model] : undefined;
+    }
+    /** Read on every request so saved changes apply to the next subagent request. */
+    subagentSpeed(model) {
+        const speeds = this.current.providers.codex?.subagentSpeeds;
+        return speeds && Object.hasOwn(speeds, model) ? speeds[model] : 'standard';
+    }
+    /** The Settings-page Claude cache TTL; undefined follows the plugin config. Read per request, so no clone. */
+    promptCacheTtl() {
+        return this.current.providers.claude?.promptCacheTtl;
+    }
+    /** Creation-time policy survives restarts and never changes an existing session. */
+    toolEnabled(provider, tool, createdAt = Date.now()) {
+        let enabled = true;
+        for (const revision of this.current.toolHistory) {
+            if (revision.at > createdAt)
+                break;
+            if (revision.provider === provider)
+                enabled = revision.tools[tool] !== false;
+        }
+        return enabled;
+    }
+    set(provider, input) {
+        const preferences = validatePreferences(provider, input);
+        const run = this.writes.then(async () => {
+            const next = structuredClone(this.current);
+            const before = next.providers[provider]?.tools ?? {};
+            next.providers[provider] = preferences;
+            if (PROVIDER_TOOLS[provider].some(tool => (before[tool] !== false) !== (preferences.tools?.[tool] !== false))) {
+                next.toolHistory.push({ at: Date.now(), provider, tools: preferences.tools ?? {} });
+            }
+            await mkdir(dirname(this.path), { recursive: true });
+            const temporary = `${this.path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify(next, null, 2), { mode: 0o600 });
+                await rename(temporary, this.path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+            this.current = next;
+        });
+        this.writes = run.catch(() => undefined);
+        return run;
+    }
+}