@timurproko/a1 0.1.1-dev.6 → 0.1.1-dev.7

package/dist/src/foundation/owned-ui-settings/resolution.js

@@ -0,0 +1,147 @@
+import { OWNED_UI_SETTINGS_VERSION, findOwnedUiSettingDeclaration, } from "./declarations.js";
+import { migrationsFrom } from "./migrations.js";
+export function parseOwnedUiSettingsDocument(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    const version = candidate["version"];
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
+        return null;
+    const values = candidate["values"];
+    if (typeof values !== "object" || values === null || Array.isArray(values))
+        return null;
+    return { version, values: values };
+}
+/**
+ * Pure resolution: declarations plus a parsed document produce a complete value
+ * set, the keys to preserve, and every notice worth reporting. Never throws.
+ */
+export function resolveOwnedUiSettings(input) {
+    const currentVersion = input.currentVersion ?? OWNED_UI_SETTINGS_VERSION;
+    const notices = [];
+    if (input.unreadableDetail !== undefined) {
+        notices.push({ code: "document-unreadable", settingId: null, detail: input.unreadableDetail });
+    }
+    if (input.document === null) {
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({}),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    if (input.document.version > currentVersion) {
+        notices.push({
+            code: "version-newer-than-supported",
+            settingId: null,
+            detail: `stored version ${input.document.version} is newer than supported version ${currentVersion}`,
+        });
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({ ...input.document.values }),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    const pending = migrationsFrom(input.migrations, input.document.version);
+    const expected = currentVersion - input.document.version;
+    if (pending.length !== expected) {
+        notices.push({
+            code: "migration-unavailable",
+            settingId: null,
+            detail: `no declared migration path from stored version ${input.document.version} to ${currentVersion}`,
+        });
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({ ...input.document.values }),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    let values = { ...input.document.values };
+    for (const migration of pending) {
+        try {
+            values = { ...migration.migrate(Object.freeze({ ...values })) };
+        }
+        catch (error) {
+            notices.push({
+                code: "migration-unavailable",
+                settingId: null,
+                detail: `migration to version ${migration.to} failed: ${describe(error)}`,
+            });
+            return {
+                version: currentVersion,
+                settings: defaultsFor(input.declarations),
+                preserved: Object.freeze({ ...input.document.values }),
+                notices: Object.freeze(notices),
+                migrated: false,
+            };
+        }
+    }
+    const settings = [];
+    for (const declaration of input.declarations) {
+        if (!Object.hasOwn(values, declaration.id)) {
+            settings.push({ declaration, value: declaration.defaultValue, source: "default" });
+            continue;
+        }
+        const stored = values[declaration.id];
+        if (isAllowed(declaration, stored)) {
+            settings.push({ declaration, value: stored, source: "stored" });
+            continue;
+        }
+        notices.push({
+            code: "value-rejected",
+            settingId: declaration.id,
+            detail: `stored value ${JSON.stringify(stored) ?? "undefined"} is not an allowed value`,
+        });
+        settings.push({ declaration, value: declaration.defaultValue, source: "default" });
+    }
+    const preserved = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (findOwnedUiSettingDeclaration(input.declarations, key) === null)
+            preserved[key] = value;
+    }
+    return {
+        version: currentVersion,
+        settings: Object.freeze(settings),
+        preserved: Object.freeze(preserved),
+        notices: Object.freeze(notices),
+        migrated: pending.length > 0,
+    };
+}
+export function settingValue(resolution, id) {
+    return resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
+}
+export function documentFrom(resolution) {
+    const values = { ...resolution.preserved };
+    for (const setting of resolution.settings) {
+        if (setting.source === "stored")
+            values[setting.declaration.id] = setting.value;
+    }
+    return { version: resolution.version, values };
+}
+function defaultsFor(declarations) {
+    return Object.freeze(declarations.map(declaration => ({
+        declaration,
+        value: declaration.defaultValue,
+        source: "default",
+    })));
+}
+function isAllowed(declaration, value) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean")
+        return false;
+    return declaration.allowedValues.includes(value);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/foundation/owned-ui-settings/sections.d.ts

@@ -0,0 +1,70 @@
+import type { OwnedUiSettingValue } from "./declarations.js";
+import type { OwnedUiSettingsResolution } from "./resolution.js";
+export type OwnedUiSettingsBackend = "a1" | "agent";
+export interface OwnedUiSettingsEntry {
+    readonly id: string;
+    /** Label to show, when its source provides one. Falls back to the id. */
+    readonly label: string | null;
+    readonly backend: OwnedUiSettingsBackend;
+    readonly description: string | null;
+    /** Present when the value is a scalar the surface can offer as a choice. */
+    readonly value: OwnedUiSettingValue | null;
+    /** Raw value as reported by its backend, for entries the surface can only display. */
+    readonly rawValue: unknown;
+    readonly editable: boolean;
+    readonly choices: readonly OwnedUiSettingValue[] | null;
+    /** True when the value is a structured object edited through its own surface. */
+    readonly structured: boolean;
+    /** Limits a numeric setting accepts, when the engine states them. */
+    readonly minimum: number | null;
+    readonly maximum: number | null;
+    /** Flags that surface offers, declared by the source rather than by the value. */
+    readonly flags: readonly {
+        readonly key: string;
+        readonly label: string;
+        readonly description: string;
+        readonly fallback: boolean;
+    }[];
+    readonly origin: "default" | "stored" | "engine";
+    readonly application: "live" | "restart" | "engine";
+}
+export interface OwnedUiSettingsSection {
+    readonly id: string;
+    readonly title: string;
+    readonly entries: readonly OwnedUiSettingsEntry[];
+    /** Set when the section could not be built; entries is then empty. */
+    readonly unavailableReason: string | null;
+    /** Set when the section is present but nothing in it can be changed here. */
+    readonly readOnlyReason: string | null;
+}
+export interface AgentSettingsSnapshot {
+    readonly descriptors: readonly {
+        readonly key: string;
+        readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+        readonly writable: boolean;
+        readonly choices?: readonly unknown[];
+        readonly label?: string;
+        readonly description?: string;
+        readonly minimum?: number;
+        readonly maximum?: number;
+        readonly flags?: readonly {
+            readonly key: string;
+            readonly label: string;
+            readonly description: string;
+            readonly fallback: boolean;
+        }[];
+    }[];
+    readonly values: Readonly<Record<string, unknown>>;
+    /** Whether the engine advertises settings write capability at all. */
+    readonly writeAdvertised: boolean;
+    /** Set when the engine could not report its settings. */
+    readonly failure: string | null;
+}
+export interface BuildOwnedUiSettingsSectionsInput {
+    readonly resolution: OwnedUiSettingsResolution;
+    /** Null when no engine is attached, which is not a failure. */
+    readonly agent: AgentSettingsSnapshot | null;
+}
+export declare const AGENT_SECTION_ID = "agent";
+export declare function buildOwnedUiSettingsSections(input: BuildOwnedUiSettingsSectionsInput): readonly OwnedUiSettingsSection[];
+export declare function findOwnedUiSettingsEntry(sections: readonly OwnedUiSettingsSection[], id: string, backend: OwnedUiSettingsBackend): OwnedUiSettingsEntry | null;

package/dist/src/foundation/owned-ui-settings/sections.js

@@ -0,0 +1,93 @@
+export const AGENT_SECTION_ID = "agent";
+const BOOLEAN_CHOICES = Object.freeze([true, false]);
+export function buildOwnedUiSettingsSections(input) {
+    const ownedSection = {
+        id: "a1",
+        title: "A1",
+        entries: Object.freeze(input.resolution.settings.map(setting => ({
+            id: setting.declaration.id,
+            label: null,
+            backend: "a1",
+            description: setting.declaration.description,
+            value: setting.value,
+            rawValue: setting.value,
+            editable: true,
+            structured: false,
+            minimum: null,
+            maximum: null,
+            flags: [],
+            choices: setting.declaration.allowedValues,
+            origin: setting.source,
+            application: setting.declaration.application,
+        }))),
+        unavailableReason: null,
+        readOnlyReason: null,
+    };
+    return Object.freeze([ownedSection, agentSection(input.agent)]);
+}
+export function findOwnedUiSettingsEntry(sections, id, backend) {
+    for (const section of sections) {
+        const entry = section.entries.find(candidate => candidate.id === id && candidate.backend === backend);
+        if (entry)
+            return entry;
+    }
+    return null;
+}
+function agentSection(snapshot) {
+    if (snapshot === null) {
+        return frozenSection("Agent settings are unavailable because no agent engine is attached", null, []);
+    }
+    if (snapshot.failure !== null) {
+        return frozenSection(`Agent settings are unavailable: ${snapshot.failure}`, null, []);
+    }
+    if (snapshot.descriptors.length === 0) {
+        return frozenSection("The agent engine reported no settings", null, []);
+    }
+    const entries = snapshot.descriptors.map(descriptor => {
+        const raw = Object.hasOwn(snapshot.values, descriptor.key) ? snapshot.values[descriptor.key] : null;
+        return {
+            id: descriptor.key,
+            label: descriptor.label ?? null,
+            backend: "agent",
+            description: descriptor.description ?? null,
+            value: scalar(raw),
+            rawValue: raw,
+            // A structured value is editable through its own surface rather than a
+            // value menu, so it stays reachable instead of being reported as fixed.
+            editable: snapshot.writeAdvertised && descriptor.writable,
+            structured: descriptor.valueType === "json",
+            minimum: descriptor.minimum ?? null,
+            maximum: descriptor.maximum ?? null,
+            flags: descriptor.flags ?? [],
+            // A boolean is a two-value choice even when the engine names no choices,
+            // so it opens the same menu as any other enumerated setting.
+            choices: descriptor.valueType === "boolean" ? BOOLEAN_CHOICES : choicesOf(descriptor.choices),
+            origin: "engine",
+            application: "engine",
+        };
+    });
+    const readOnlyReason = snapshot.writeAdvertised
+        ? (entries.some(entry => entry.editable)
+            ? null
+            : "The agent engine reports no writable settings")
+        : "The agent engine does not support changing settings from this surface";
+    return {
+        id: AGENT_SECTION_ID,
+        title: "Agent",
+        entries: Object.freeze(entries),
+        unavailableReason: null,
+        readOnlyReason,
+    };
+}
+function frozenSection(unavailableReason, readOnlyReason, entries) {
+    return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze(entries), unavailableReason, readOnlyReason };
+}
+function scalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : null;
+}
+function choicesOf(choices) {
+    if (choices === undefined)
+        return null;
+    const scalars = choices.map(scalar).filter((choice) => choice !== null);
+    return scalars.length === choices.length ? Object.freeze(scalars) : null;
+}

package/dist/src/foundation/owned-ui-settings/session.d.ts

@@ -0,0 +1,44 @@
+import type { AgentSettingsPort } from "../agent-engine-contracts/index.js";
+import type { OwnedUiSettingValue } from "./declarations.js";
+import type { OwnedUiSettingsResolution } from "./resolution.js";
+import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
+import type { OwnedUiSettingsStore } from "./store.js";
+export interface OwnedUiSettingsChangeOutcome {
+    readonly applied: boolean;
+    /** True when the value is stored but only takes effect on the next start. */
+    readonly pendingRestart: boolean;
+    /** Present when the change could not be persisted; the surface must not show it as saved. */
+    readonly failure: string | null;
+}
+export interface OwnedUiSettingsSessionOptions {
+    readonly store: OwnedUiSettingsStore;
+    /** Null when no engine is attached; the Agent section then reports itself unavailable. */
+    readonly agent?: AgentSettingsPort | null;
+    /**
+     * Resolves the port at load time instead of construction time, for an engine
+     * whose runtime is not up yet. Takes precedence over `agent`.
+     */
+    readonly agentProvider?: () => AgentSettingsPort | null;
+}
+export type OwnedUiSettingsListener = (session: OwnedUiSettingsSession) => void;
+/**
+ * Holds the resolved settings for one owned UI session and routes every accepted
+ * change to the backend that owns it: A1 settings to the A1 document, agent
+ * settings to the engine settings port. Neither backend ever sees the other's value.
+ */
+export declare class OwnedUiSettingsSession {
+    #private;
+    constructor(options: OwnedUiSettingsSessionOptions);
+    get resolution(): OwnedUiSettingsResolution;
+    /** Reads the engine's settings so the Agent section can be built. Never throws. */
+    load(): Promise<void>;
+    sections(): readonly OwnedUiSettingsSection[];
+    /** Resolved value of an A1 setting, or null when it is not declared. */
+    value(id: string): OwnedUiSettingValue | null;
+    /** Value stored this session but not yet in effect, for a restart-required setting. */
+    pendingValue(id: string): OwnedUiSettingValue | null;
+    onChange(listener: OwnedUiSettingsListener): () => void;
+    /** Writes a structured value, which only an engine-backed setting can hold. */
+    changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
+    change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
+}

package/dist/src/foundation/owned-ui-settings/session.js

@@ -0,0 +1,145 @@
+import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
+/**
+ * Holds the resolved settings for one owned UI session and routes every accepted
+ * change to the backend that owns it: A1 settings to the A1 document, agent
+ * settings to the engine settings port. Neither backend ever sees the other's value.
+ */
+export class OwnedUiSettingsSession {
+    #store;
+    #agent;
+    #agentProvider;
+    #listeners = new Set();
+    #resolution;
+    #agentSnapshot = null;
+    #pending = new Map();
+    constructor(options) {
+        this.#store = options.store;
+        this.#agent = options.agent ?? null;
+        this.#agentProvider = options.agentProvider ?? null;
+        this.#resolution = options.store.read();
+    }
+    get resolution() {
+        return this.#resolution;
+    }
+    /** Reads the engine's settings so the Agent section can be built. Never throws. */
+    async load() {
+        this.#resolution = this.#store.read();
+        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent);
+        this.#notify();
+    }
+    sections() {
+        return buildOwnedUiSettingsSections({ resolution: this.#resolution, agent: this.#agentSnapshot });
+    }
+    /** Resolved value of an A1 setting, or null when it is not declared. */
+    value(id) {
+        return this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
+    }
+    /** Value stored this session but not yet in effect, for a restart-required setting. */
+    pendingValue(id) {
+        return this.#pending.get(id) ?? null;
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    /** Writes a structured value, which only an engine-backed setting can hold. */
+    async changeStructured(backend, id, value) {
+        if (backend !== "agent")
+            return failed("only an agent setting holds a structured value");
+        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+        if (agent === null)
+            return failed("no agent engine is attached");
+        if (!agent.capabilities.write || !agent.writeSetting) {
+            return failed("the agent engine does not support changing settings from this surface");
+        }
+        try {
+            await agent.writeSetting(id, value);
+            if (agent.capabilities.flush && agent.flush)
+                await agent.flush();
+        }
+        catch (error) {
+            return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
+        }
+        this.#agentSnapshot = await snapshotOf(agent);
+        this.#notify();
+        return { applied: true, pendingRestart: false, failure: null };
+    }
+    async change(backend, id, value) {
+        const entry = findOwnedUiSettingsEntry(this.sections(), id, backend);
+        if (entry === null)
+            return failed(`unknown ${backend} setting: ${id}`);
+        if (!entry.editable)
+            return failed(`${id} is not editable from this surface`);
+        return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgent(id, value);
+    }
+    #changeOwned(id, value) {
+        const outcome = this.#store.write(this.#resolution, id, value);
+        if (!outcome.stored)
+            return failed(outcome.failure ?? `${id} could not be stored`);
+        const previous = this.#resolution;
+        this.#resolution = this.#store.read();
+        const declaration = previous.settings.find(setting => setting.declaration.id === id)?.declaration;
+        if (declaration?.application === "restart") {
+            this.#pending.set(id, value);
+            this.#resolution = previous;
+            this.#notify();
+            return { applied: false, pendingRestart: true, failure: null };
+        }
+        this.#pending.delete(id);
+        this.#notify();
+        return { applied: true, pendingRestart: false, failure: null };
+    }
+    async #changeAgent(id, value) {
+        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+        if (agent === null)
+            return failed("no agent engine is attached");
+        if (!agent.capabilities.write || !agent.writeSetting) {
+            return failed("the agent engine does not support changing settings from this surface");
+        }
+        try {
+            await agent.writeSetting(id, value);
+            if (agent.capabilities.flush && agent.flush)
+                await agent.flush();
+        }
+        catch (error) {
+            return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
+        }
+        this.#agentSnapshot = await snapshotOf(agent);
+        this.#notify();
+        return { applied: true, pendingRestart: false, failure: null };
+    }
+    #notify() {
+        for (const listener of this.#listeners)
+            listener(this);
+    }
+}
+async function snapshotOf(agent) {
+    try {
+        const descriptors = await agent.listSettings();
+        const values = {};
+        for (const descriptor of descriptors) {
+            try {
+                values[descriptor.key] = await agent.readSetting(descriptor.key) ?? null;
+            }
+            catch {
+                values[descriptor.key] = null;
+            }
+        }
+        return {
+            descriptors,
+            values,
+            writeAdvertised: agent.capabilities.write && typeof agent.writeSetting === "function",
+            failure: null,
+        };
+    }
+    catch (error) {
+        return { descriptors: [], values: {}, writeAdvertised: false, failure: describe(error) };
+    }
+}
+function failed(failure) {
+    return { applied: false, pendingRestart: false, failure };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/foundation/owned-ui-settings/store.d.ts

@@ -0,0 +1,28 @@
+import { type OwnedUiSettingDeclaration, type OwnedUiSettingValue } from "./declarations.js";
+import { type OwnedUiSettingsMigration } from "./migrations.js";
+import { type OwnedUiSettingsResolution } from "./resolution.js";
+export interface OwnedUiSettingsStoreOptions {
+    /** A1 configuration root. Settings live under `<configDir>/settings/`. */
+    readonly configDir: string;
+    readonly profileId: string;
+    readonly declarations?: readonly OwnedUiSettingDeclaration[];
+    readonly migrations?: readonly OwnedUiSettingsMigration[];
+}
+export interface OwnedUiSettingsWriteOutcome {
+    readonly stored: boolean;
+    /** Present when the write failed; the caller must not report the change as saved. */
+    readonly failure: string | null;
+}
+export declare class OwnedUiSettingsStore {
+    #private;
+    constructor(options: OwnedUiSettingsStoreOptions);
+    get file(): string;
+    /** Reads and resolves. Never throws: every failure becomes a notice. */
+    read(): OwnedUiSettingsResolution;
+    /**
+     * Writes the resolved form with `id` set to `value`, preserving undeclared keys.
+     * Atomic: a temporary sibling is renamed over the target, so an interrupted
+     * write leaves either the complete previous document or the complete new one.
+     */
+    write(resolution: OwnedUiSettingsResolution, id: string, value: OwnedUiSettingValue): OwnedUiSettingsWriteOutcome;
+}

package/dist/src/foundation/owned-ui-settings/store.js

@@ -0,0 +1,90 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, } from "./declarations.js";
+import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
+import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
+const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const MAX_DOCUMENT_BYTES = 256 * 1024;
+export class OwnedUiSettingsStore {
+    #file;
+    #declarations;
+    #migrations;
+    constructor(options) {
+        if (!PROFILE_ID_PATTERN.test(options.profileId)) {
+            throw new Error(`owned UI settings profile id is not a bounded slug: ${options.profileId}`);
+        }
+        this.#file = path.join(path.resolve(options.configDir), "settings", `${options.profileId}.json`);
+        this.#declarations = options.declarations ?? OWNED_UI_SETTING_DECLARATIONS;
+        this.#migrations = options.migrations ?? OWNED_UI_SETTINGS_MIGRATIONS;
+    }
+    get file() {
+        return this.#file;
+    }
+    /** Reads and resolves. Never throws: every failure becomes a notice. */
+    read() {
+        let raw = null;
+        let unreadable = null;
+        try {
+            raw = readFileSync(this.#file, "utf8");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                unreadable = `${this.#file} could not be read: ${describe(error)}`;
+        }
+        if (raw !== null && Buffer.byteLength(raw, "utf8") > MAX_DOCUMENT_BYTES) {
+            unreadable = `${this.#file} exceeds the ${MAX_DOCUMENT_BYTES}-byte settings limit and was ignored`;
+            raw = null;
+        }
+        const document = raw === null ? null : parseOwnedUiSettingsDocument(raw);
+        if (raw !== null && document === null && unreadable === null) {
+            unreadable = `${this.#file} is not a valid settings document and was ignored`;
+        }
+        return resolveOwnedUiSettings({
+            declarations: this.#declarations,
+            migrations: this.#migrations,
+            document,
+            ...(unreadable === null ? {} : { unreadableDetail: unreadable }),
+            currentVersion: OWNED_UI_SETTINGS_VERSION,
+        });
+    }
+    /**
+     * Writes the resolved form with `id` set to `value`, preserving undeclared keys.
+     * Atomic: a temporary sibling is renamed over the target, so an interrupted
+     * write leaves either the complete previous document or the complete new one.
+     */
+    write(resolution, id, value) {
+        const declaration = this.#declarations.find(candidate => candidate.id === id);
+        if (!declaration)
+            return { stored: false, failure: `unknown owned UI setting: ${id}` };
+        if (!declaration.allowedValues.includes(value)) {
+            return { stored: false, failure: `value ${JSON.stringify(value)} is not allowed for ${id}` };
+        }
+        const current = documentFrom(resolution);
+        const next = {
+            version: OWNED_UI_SETTINGS_VERSION,
+            values: { ...current.values, [id]: value },
+        };
+        const temporary = `${this.#file}.${process.pid}.tmp`;
+        try {
+            mkdirSync(path.dirname(this.#file), { recursive: true, mode: 0o700 });
+            writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+            renameSync(temporary, this.#file);
+            return { stored: true, failure: null };
+        }
+        catch (error) {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch {
+                // A leftover temporary file is inert: read() only ever opens the target path.
+            }
+            return { stored: false, failure: `${this.#file} could not be written: ${describe(error)}` };
+        }
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/foundation/pi-component-adapter/index.d.ts

@@ -3,6 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
+export { getAvailablePiThemes } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/src/foundation/pi-component-adapter/index.js

@@ -3,6 +3,7 @@ export * from "./conformance.js";
 export * from "./shell-components.js";
 export * from "./theme.js";
 export * from "./upstream/theme/theme-controller.js";
+export { getAvailablePiThemes } from "./upstream/theme/theme.js";
 export * from "./upstream/components/countdown-timer.js";
 export * from "./upstream/components/extension-editor.js";
 export * from "./upstream/components/session-selector.js";

package/dist/src/foundation/pi-component-adapter/shell-selectors-dialogs.d.ts

@@ -93,7 +93,15 @@ export declare function createPiShellDaxnuts(runtime: Pick<PiShellEditorOptions,
 export declare function createPiShellEarendilAnnouncement(): PiShellComponentPort;
 export declare function createPiShellOperationLoader(runtime: Pick<PiShellEditorOptions, "getColumns" | "getRows" | "requestRender">, message: string): PiShellComponentPort;
 export declare function createPiShellReloadBox(): PiShellComponentPort;
-export declare function createPiShellAuthProviderSelector(mode: "login" | "logout", providers: readonly PiShellSelectorOption[], onSelect: (id: string) => void, onCancel: () => void): PiShellComponentPort;
+export interface PiShellAuthProviderOption extends PiShellSelectorOption {
+    readonly providerId: string;
+    readonly authType: "oauth" | "api_key";
+    readonly status?: {
+        readonly type: "oauth" | "api_key";
+        readonly source?: string;
+    };
+}
+export declare function createPiShellAuthProviderSelector(mode: "login" | "logout", providers: readonly PiShellAuthProviderOption[], onSelect: (id: string) => void, onCancel: () => void): PiShellComponentPort;
 export declare function createPiShellExtensionSelector(title: string, options: readonly string[], onSelect: (value: string) => void, onCancel: () => void): PiShellComponentPort;
 export declare function createPiShellThinkingSelector(currentLevel: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", availableLevels: readonly ("off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[], onSelect: (level: string) => void, onCancel: () => void): PiShellComponentPort;
 export declare function createPiShellThemeSelector(currentTheme: string, onSelect: (theme: string) => void, onCancel: () => void, onPreview: (theme: string) => void): PiShellComponentPort;