@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/dist/ui/components/value-menu.d.ts

@@ -0,0 +1,43 @@
+import type { UiTheme } from "./theme.js";
+/**
+ * The menu a value opens: anchored to the row it was opened from, marking what
+ * is in effect, highlighting nothing until something is picked, and flipping
+ * above its anchor only when it would otherwise run off the bottom.
+ */
+export interface ValueMenuState {
+    /** Values offered, as they should read. */
+    readonly choices: readonly string[];
+    /** The value in effect, marked rather than highlighted. */
+    readonly current: string | null;
+    /** The entry picked by a key or the pointer, or -1 while none is. */
+    readonly index: number;
+}
+export interface ValueMenuAnchor {
+    /** Row the menu was opened from, which it keeps even as the selection moves. */
+    readonly screenRow: number;
+    /** Column the values start at. */
+    readonly valueColumn: number;
+}
+/** Where a menu sits on screen, for reading a pointer against it. */
+export interface ValueMenuFrame {
+    readonly top: number;
+    readonly column: number;
+    readonly width: number;
+    readonly rows: number;
+}
+export interface ValueMenuLayout {
+    /** First screen row available to the menu. Defaults to zero. */
+    readonly bodyTop?: number;
+    /** Rows available between the fixed header and footer. */
+    readonly bodyHeight: number;
+    /** Full surface width, so the menu stays inside it. */
+    readonly surfaceWidth: number;
+    /** Columns reserved at the right edge, such as a scrollbar rail. */
+    readonly reservedRight: number;
+}
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export declare function valueMenuFrame(state: ValueMenuState, anchor: ValueMenuAnchor, layout: ValueMenuLayout): ValueMenuFrame;
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export declare function renderValueMenu(lines: readonly string[], state: ValueMenuState, frame: ValueMenuFrame, theme: UiTheme): readonly string[];
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export declare function menuRowAt(frame: ValueMenuFrame, row: number, column: number): number | null;

package/dist/ui/components/value-menu.js

@@ -0,0 +1,41 @@
+import { overlaySpan } from "./spans.js";
+import { displayWidth, padToWidth } from "./text.js";
+/** Where the menu is placed: below its anchor where there is room, else above. */
+export function valueMenuFrame(state, anchor, layout) {
+    const bodyTop = layout.bodyTop ?? 0;
+    const bodyBottom = bodyTop + layout.bodyHeight;
+    const below = anchor.screenRow + 1;
+    const top = below + state.choices.length <= bodyBottom
+        ? below
+        : Math.max(bodyTop, anchor.screenRow - state.choices.length);
+    const width = Math.max(...state.choices.map(choice => displayWidth(choice) + 4), 6);
+    const column = Math.min(anchor.valueColumn, Math.max(0, layout.surfaceWidth - width - layout.reservedRight));
+    return { top, column, width, rows: state.choices.length };
+}
+/** Draws the menu over the rows behind it, leaving them otherwise untouched. */
+export function renderValueMenu(lines, state, frame, theme) {
+    const output = [...lines];
+    state.choices.forEach((choice, index) => {
+        const target = frame.top + index;
+        if (target < 0 || target >= output.length)
+            return;
+        const active = index === state.index;
+        const paint = active ? theme.highlight : theme.panel;
+        const current = choice === state.current;
+        const tail = padToWidth(`${current ? " " : "  "}${choice} `, frame.width - (current ? 1 : 0));
+        // Invariant: the effective-value check uses the same accent as modal marks, while
+        // the rest of an active row keeps its highlighted foreground and background.
+        const painted = current
+            ? `${paint(theme.fg("accent", "✓"))}${paint(tail)}`
+            : paint(tail);
+        output[target] = overlaySpan(output[target] ?? "", frame.column, frame.column + frame.width, painted);
+    });
+    return output;
+}
+/** Whether a pointer report lands inside the menu rather than behind it. */
+export function menuRowAt(frame, row, column) {
+    const at = row - frame.top;
+    if (at < 0 || at >= frame.rows)
+        return null;
+    return column > frame.column && column <= frame.column + frame.width ? at : null;
+}

package/dist/ui/components/visible-hyperlinks.d.ts

@@ -0,0 +1,26 @@
+export interface VisibleHyperlinkRange {
+    readonly from: number;
+    readonly to: number;
+    readonly target: string;
+    readonly kind: "explicit" | "candidate";
+}
+export interface VisibleHyperlinkRow {
+    readonly ranges: readonly VisibleHyperlinkRange[];
+    /**
+     * Whether the row declares a terminal hyperlink of its own. Only a declared link gives the
+     * terminal per-cell link identity that moving the row can misattribute, so movement safety
+     * asks this rather than counting ranges: a candidate range is host-hover text such as
+     * `obj.method` or `./src/index.ts`, which ordinary code produces on nearly every row.
+     */
+    readonly hasExplicitLink: boolean;
+    /** False for unclosed links, malformed escapes, images, or row-moving controls. */
+    readonly replaySafe: boolean;
+    readonly width: number;
+    /** Paint identity includes labels, not just targets; it never changes source bytes. */
+    readonly signature: string;
+}
+/**
+ * Reads final visible row geometry without decorating text. Candidate ranges
+ * only invalidate host-hover paint; they never invent an explicit link target.
+ */
+export declare function readVisibleHyperlinks(line: string, widthOf?: (text: string) => number): VisibleHyperlinkRow;

package/dist/ui/components/visible-hyperlinks.js

@@ -0,0 +1,97 @@
+import { displayWidth } from "./text.js";
+/** Linear tokenization: a valid large OSC target must not exhaust the regular-expression engine's stack. */
+function* rowTokens(line) {
+    const oscBoundary = /[\u0007\u001b]/g;
+    for (let offset = 0; offset < line.length;) {
+        if (line.charCodeAt(offset) !== 27) {
+            const next = line.indexOf("\u001b", offset);
+            const end = next < 0 ? line.length : next;
+            yield line.slice(offset, end);
+            offset = end;
+            continue;
+        }
+        let end = offset + 1;
+        if (line[offset + 1] === "[") {
+            let cursor = offset + 2;
+            while (line.charCodeAt(cursor) >= 0x30 && line.charCodeAt(cursor) <= 0x3f)
+                cursor++;
+            while (line.charCodeAt(cursor) >= 0x20 && line.charCodeAt(cursor) <= 0x2f)
+                cursor++;
+            if (line.charCodeAt(cursor) >= 0x40 && line.charCodeAt(cursor) <= 0x7e)
+                end = cursor + 1;
+        }
+        else if (line[offset + 1] === "]") {
+            // Performance: search for one boundary, not a quantified alternation over the entire URI.
+            oscBoundary.lastIndex = offset + 2;
+            const boundary = oscBoundary.exec(line);
+            if (boundary?.[0] === "\u0007")
+                end = boundary.index + 1;
+            else if (boundary !== null && line[boundary.index + 1] === "\\")
+                end = boundary.index + 2;
+        }
+        yield line.slice(offset, end);
+        offset = end;
+    }
+}
+const SGR = /^\u001b\[[\d;:]*m$/u;
+const SEMANTIC_ZONE = /^\u001b\]133;[ABC](?:\u0007|\u001b\\)$/u;
+// Platform: this is a conservative cleanup detector, NOT a link-activation
+// parser. Hosts recognize URLs, domains and file-like labels without OSC 8.
+const CANDIDATE = /(?:[a-z][a-z\d+.-]*:\/\/[^\s<>"']+|www\.[^\s<>"']+|(?:[a-z]:[\\/]|\.{1,2}[\\/])[^\s<>"']+|[\p{L}\p{N}_-]+(?:\.\p{L}[\p{L}\p{N}_-]+)+(?:[\\/][^\s<>"']+)?)/giu;
+/**
+ * Reads final visible row geometry without decorating text. Candidate ranges
+ * only invalidate host-hover paint; they never invent an explicit link target.
+ */
+export function readVisibleHyperlinks(line, widthOf = displayWidth) {
+    const ranges = [];
+    let plain = "";
+    let column = 0;
+    let active;
+    let replaySafe = true;
+    const finish = () => {
+        if (active !== undefined && column > active.from) {
+            ranges.push({ from: active.from, to: column, target: active.target, kind: "explicit" });
+        }
+        active = undefined;
+    };
+    for (const token of rowTokens(line)) {
+        if (token.startsWith("\u001b")) {
+            const separator = token.startsWith("\u001b]8;") ? token.indexOf(";", 4) : -1;
+            if (separator !== -1) {
+                finish();
+                const target = token.slice(separator + 1, token.endsWith("\u0007") ? -1 : -2);
+                if (target)
+                    active = { from: column, target };
+            }
+            else if (!SGR.test(token) && !SEMANTIC_ZONE.test(token))
+                replaySafe = false;
+        }
+        else {
+            if (/[\u0000-\u001f\u007f]/u.test(token))
+                replaySafe = false;
+            plain += token;
+            column += widthOf(token);
+        }
+    }
+    if (active !== undefined) {
+        replaySafe = false;
+        finish();
+    }
+    for (const match of plain.matchAll(CANDIDATE)) {
+        const from = widthOf(plain.slice(0, match.index));
+        const to = from + widthOf(match[0]);
+        if (!ranges.some(range => from < range.to && to > range.from)) {
+            ranges.push({ from, to, target: match[0], kind: "candidate" });
+        }
+    }
+    ranges.sort((left, right) => left.from - right.from);
+    return {
+        ranges,
+        hasExplicitLink: ranges.some(range => range.kind === "explicit"),
+        replaySafe,
+        width: column,
+        // Rationale: a path with spaces or a wrapped host match may extend beyond
+        // the conservative candidate. Changes anywhere in that row invalidate it.
+        signature: ranges.length === 0 ? "" : JSON.stringify([ranges, plain]),
+    };
+}

package/dist/ui/settings/declarations.d.ts

@@ -0,0 +1,127 @@
+export declare const OWNED_UI_SETTINGS_VERSION = 8;
+export type OwnedUiSettingValue = string | number | boolean;
+export type OwnedUiSettingApplication = "live" | "restart";
+export interface OwnedUiSettingDeclaration {
+    readonly id: string;
+    /** Optional presentation label; the id remains the persistence key. */
+    readonly label?: string;
+    /** Optional settings-screen group for related owned controls. */
+    readonly section?: {
+        readonly id: string;
+        readonly title: string;
+    };
+    readonly description: string;
+    readonly application: OwnedUiSettingApplication;
+    readonly defaultValue: OwnedUiSettingValue;
+    readonly allowedValues: readonly OwnedUiSettingValue[];
+}
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
+    readonly quitAnimation: Readonly<{
+        id: "quitAnimation";
+        label: "Quit animation";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Play the fall effect over the last screen when the session quits. Off returns to the terminal immediately.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly scrollbarAppearance: Readonly<{
+        id: "scrollbarAppearance";
+        label: "Scrollbar mode";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "When the session transcript scrollbar is visible.";
+        application: "live";
+        defaultValue: "auto";
+        allowedValues: readonly ["auto", "always", "hidden"];
+    }>;
+    readonly scrollbarStyle: Readonly<{
+        id: "scrollbarStyle";
+        label: "Scrollbar style";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Visual weight of the session transcript scrollbar.";
+        application: "live";
+        defaultValue: "thin";
+        allowedValues: readonly ["thin", "thick"];
+    }>;
+    readonly scrollbarSpeed: Readonly<{
+        id: "scrollbarSpeed";
+        label: "Speed";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Distance moved by each session transcript wheel event.";
+        application: "live";
+        defaultValue: "normal";
+        allowedValues: readonly ["normal", "fast", "high"];
+    }>;
+    readonly promptHistoryEnabled: Readonly<{
+        id: "promptHistoryEnabled";
+        label: "Persistent history";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Retain reusable prompts across sessions. Applies on next start; disabling does not erase saved history or stop existing instances.";
+        application: "restart";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly promptHistoryMaxItems: Readonly<{
+        id: "promptHistoryMaxItems";
+        label: "History limit";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Maximum recent unique prompts after next start. Byte limits also apply; increasing the limit cannot restore pruned entries.";
+        application: "restart";
+        defaultValue: 100;
+        allowedValues: readonly [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+    }>;
+    readonly promptSuggestions: Readonly<{
+        id: "promptSuggestions";
+        label: "Prompt suggestions";
+        section: Readonly<{
+            id: "agent";
+            title: "Agent";
+        }>;
+        description: "Predict likely next prompts with one additional background request using the selected model.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly skillsPresentation: Readonly<{
+        id: "skillsPresentation";
+        label: "Skills";
+        section: Readonly<{
+            id: "agent";
+            title: "Agent";
+        }>;
+        description: "Collapse offers one /skills command with a searchable dialog and the /skills: shortcut; expand lists every /skill:<name> command directly.";
+        application: "live";
+        defaultValue: "collapse";
+        allowedValues: readonly ["collapse", "expand"];
+    }>;
+}>;
+export type OwnedSettingId = keyof typeof OWNED_SETTING_DECLARATIONS;
+/** The value type a setting's declaration allows: a literal union for a choice, `number` for a stepped range. */
+export type OwnedSettingValueOf<Id extends OwnedSettingId> = (typeof OWNED_SETTING_DECLARATIONS)[Id]["allowedValues"][number];
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
+export declare const OWNED_UI_SETTING_DECLARATIONS: readonly OwnedUiSettingDeclaration[];
+export declare function isOwnedSettingId(id: string): id is OwnedSettingId;
+export declare function assertOwnedUiSettingDeclarations(declarations: readonly OwnedUiSettingDeclaration[]): void;
+export declare function findOwnedUiSettingDeclaration(declarations: readonly OwnedUiSettingDeclaration[], id: string): OwnedUiSettingDeclaration | null;

package/dist/ui/settings/declarations.js

@@ -0,0 +1,124 @@
+export const OWNED_UI_SETTINGS_VERSION = 8;
+const MAX_ID_LENGTH = 64;
+const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+/** Declared first so the settings screen opens on it; sections follow first-declaration order. */
+const GENERIC_SECTION = Object.freeze({ id: "generic", title: "Generic" });
+const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
+const AGENT_SECTION = Object.freeze({ id: "agent", title: "Agent" });
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export const OWNED_SETTING_DECLARATIONS = Object.freeze({
+    quitAnimation: Object.freeze({
+        id: "quitAnimation",
+        label: "Quit animation",
+        section: GENERIC_SECTION,
+        description: "Play the fall effect over the last screen when the session quits. Off returns to the terminal immediately.",
+        application: "live",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+    scrollbarAppearance: Object.freeze({
+        id: "scrollbarAppearance",
+        label: "Scrollbar mode",
+        section: SCROLL_SECTION,
+        description: "When the session transcript scrollbar is visible.",
+        application: "live",
+        defaultValue: "auto",
+        allowedValues: Object.freeze(["auto", "always", "hidden"]),
+    }),
+    scrollbarStyle: Object.freeze({
+        id: "scrollbarStyle",
+        label: "Scrollbar style",
+        section: SCROLL_SECTION,
+        description: "Visual weight of the session transcript scrollbar.",
+        application: "live",
+        defaultValue: "thin",
+        allowedValues: Object.freeze(["thin", "thick"]),
+    }),
+    scrollbarSpeed: Object.freeze({
+        id: "scrollbarSpeed",
+        label: "Speed",
+        section: SCROLL_SECTION,
+        description: "Distance moved by each session transcript wheel event.",
+        application: "live",
+        defaultValue: "normal",
+        allowedValues: Object.freeze(["normal", "fast", "high"]),
+    }),
+    promptHistoryEnabled: Object.freeze({
+        id: "promptHistoryEnabled",
+        label: "Persistent history",
+        section: Object.freeze({ id: "history", title: "History" }),
+        description: "Retain reusable prompts across sessions. Applies on next start; disabling does not erase saved history or stop existing instances.",
+        application: "restart",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+    promptHistoryMaxItems: Object.freeze({
+        id: "promptHistoryMaxItems",
+        label: "History limit",
+        section: Object.freeze({ id: "history", title: "History" }),
+        description: "Maximum recent unique prompts after next start. Byte limits also apply; increasing the limit cannot restore pruned entries.",
+        application: "restart",
+        defaultValue: 100,
+        allowedValues: Object.freeze([10, 20, 30, 40, 50, 60, 70, 80, 90, 100]),
+    }),
+    promptSuggestions: Object.freeze({
+        id: "promptSuggestions",
+        label: "Prompt suggestions",
+        section: AGENT_SECTION,
+        description: "Predict likely next prompts with one additional background request using the selected model.",
+        application: "live",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+    skillsPresentation: Object.freeze({
+        id: "skillsPresentation",
+        label: "Skills",
+        section: AGENT_SECTION,
+        description: "Collapse offers one /skills command with a searchable dialog and the /skills: shortcut; expand lists every /skill:<name> command directly.",
+        application: "live",
+        defaultValue: "collapse",
+        allowedValues: Object.freeze(["collapse", "expand"]),
+    }),
+});
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
+export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze(Object.values(OWNED_SETTING_DECLARATIONS));
+export function isOwnedSettingId(id) {
+    return Object.hasOwn(OWNED_SETTING_DECLARATIONS, id);
+}
+export function assertOwnedUiSettingDeclarations(declarations) {
+    const seen = new Set();
+    for (const declaration of declarations) {
+        if (!ID_PATTERN.test(declaration.id) || declaration.id.length > MAX_ID_LENGTH) {
+            throw new Error(`owned UI setting id is not a bounded camelCase identifier: ${declaration.id}`);
+        }
+        if (seen.has(declaration.id))
+            throw new Error(`duplicate owned UI setting id: ${declaration.id}`);
+        seen.add(declaration.id);
+        if (declaration.label !== undefined && declaration.label.trim().length === 0) {
+            throw new Error(`owned UI setting has an empty label: ${declaration.id}`);
+        }
+        if (declaration.section !== undefined
+            && (declaration.section.id.trim().length === 0 || declaration.section.title.trim().length === 0)) {
+            throw new Error(`owned UI setting has an invalid section: ${declaration.id}`);
+        }
+        if (declaration.description.trim().length === 0) {
+            throw new Error(`owned UI setting has no description: ${declaration.id}`);
+        }
+        if (declaration.allowedValues.length === 0) {
+            throw new Error(`owned UI setting declares no allowed values: ${declaration.id}`);
+        }
+        const types = new Set(declaration.allowedValues.map(value => typeof value));
+        if (types.size !== 1) {
+            throw new Error(`owned UI setting mixes allowed value types: ${declaration.id}`);
+        }
+        if (!declaration.allowedValues.includes(declaration.defaultValue)) {
+            throw new Error(`owned UI setting default is not an allowed value: ${declaration.id}`);
+        }
+    }
+}
+export function findOwnedUiSettingDeclaration(declarations, id) {
+    return declarations.find(declaration => declaration.id === id) ?? null;
+}

package/dist/ui/settings/index.d.ts

@@ -0,0 +1,10 @@
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export type { OwnedSettingId, OwnedSettingValueOf, OwnedUiSettingApplication, OwnedUiSettingDeclaration, OwnedUiSettingValue } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export type { OwnedUiSettingsMigration } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export type { OwnedUiResolvedSetting, OwnedUiSettingSource, OwnedUiSettingsDocument, OwnedUiSettingsNotice, OwnedUiSettingsNoticeCode, OwnedUiSettingsResolution, ResolveOwnedUiSettingsInput, } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export type { AgentSettingsSnapshot, BuildOwnedUiSettingsSectionsInput, OwnedUiSettingsBackend, OwnedUiSettingsEntry, OwnedUiSettingsSection, } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";
+export type { OwnedSettingsManagerOptions, OwnedUiSettingsChangeOutcome, OwnedUiSettingsListener } from "./manager.js";

package/dist/ui/settings/index.js

@@ -0,0 +1,5 @@
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";

package/dist/ui/settings/manager.d.ts

@@ -0,0 +1,54 @@
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/index.js";
+import { type OwnedSettingId, type OwnedSettingValueOf, type OwnedUiSettingDeclaration, type OwnedUiSettingValue } from "./declarations.js";
+import { type OwnedUiSettingsMigration } from "./migrations.js";
+import { type OwnedUiSettingsResolution } from "./resolution.js";
+import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
+export interface OwnedSettingsManagerOptions {
+    /** A1 configuration root. Settings live under `<configDir>/settings/`. */
+    readonly configDir: string;
+    readonly profileId: string;
+    readonly declarations?: readonly OwnedUiSettingDeclaration[];
+    readonly migrations?: readonly OwnedUiSettingsMigration[];
+    readonly agent?: AgentSettingsPort | null;
+    readonly agentProvider?: () => AgentSettingsPort | null;
+    readonly hiddenAgentSettingIds?: readonly string[];
+}
+export interface OwnedUiSettingsChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly applied: boolean;
+    /** Compatibility projection for existing A1 restart-bound declarations. */
+    readonly pendingRestart: boolean;
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
+    readonly failure: string | null;
+}
+export type OwnedUiSettingsListener = (manager: OwnedSettingsManager) => void;
+/**
+ * One profile's A1 settings: resolves the declaration table against the stored document,
+ * persists each accepted change atomically without discarding unknown keys, offers the
+ * grouped sections a surface presents, and routes every accepted change only to its
+ * owning backend, with agent settings reached through the engine settings port.
+ */
+export declare class OwnedSettingsManager {
+    #private;
+    constructor(options: OwnedSettingsManagerOptions);
+    get file(): string;
+    get resolution(): OwnedUiSettingsResolution;
+    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    read(): OwnedUiSettingsResolution;
+    load(): Promise<void>;
+    sections(): readonly OwnedUiSettingsSection[];
+    /**
+     * The value in effect for a declared setting, typed by its declaration. A restart-bound
+     * setting reads as the value the session started with until the next start.
+     */
+    value<Id extends OwnedSettingId>(id: Id): OwnedSettingValueOf<Id>;
+    /** The value in effect for any setting id, or null when nothing declares it. */
+    valueOf(id: string): OwnedUiSettingValue | null;
+    pendingValue(id: string): OwnedUiSettingValue | null;
+    onChange(listener: OwnedUiSettingsListener): () => void;
+    changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
+    change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
+}