@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

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/{src/foundation/owned-ui-settings → ui/settings}/declarations.d.ts

@@ -1,8 +1,15 @@
-export declare const OWNED_UI_SETTINGS_VERSION = 1;
+export declare const OWNED_UI_SETTINGS_VERSION = 4;
 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;

package/dist/ui/settings/declarations.js

@@ -0,0 +1,94 @@
+export const OWNED_UI_SETTINGS_VERSION = 4;
+const MAX_ID_LENGTH = 64;
+const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
+export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
+    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"]),
+    }),
+    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"]),
+    }),
+    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"]),
+    }),
+    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]),
+    }),
+    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]),
+    }),
+    Object.freeze({
+        id: "promptSuggestions",
+        label: "Prompt suggestions",
+        section: Object.freeze({ id: "agent", title: "Agent" }),
+        description: "Predict likely next prompts with one additional background request using the selected model.",
+        application: "live",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+]);
+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/{src/foundation/owned-ui-settings → ui/settings}/migrations.d.ts

@@ -6,7 +6,7 @@ export interface OwnedUiSettingsMigration {
 }
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
 export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
 export declare function assertOwnedUiSettingsMigrations(migrations: readonly OwnedUiSettingsMigration[], currentVersion?: number): void;

package/dist/{src/foundation/owned-ui-settings → ui/settings}/migrations.js

@@ -1,9 +1,35 @@
 import { OWNED_UI_SETTINGS_VERSION } from "./declarations.js";
 /**
  * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
- * is the first stored shape, so nothing precedes it and the list is empty.
+ * is the first stored shape.
  */
-export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([]);
+export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([
+    Object.freeze({
+        to: 2,
+        description: "Rename scrollbar speed high to fast.",
+        migrate(values) {
+            return values.scrollbarSpeed === "high"
+                ? { ...values, scrollbarSpeed: "fast" }
+                : { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 3,
+        description: "Match Pi's auto scrollbar appearance name and ordering.",
+        migrate(values) {
+            return values.scrollbarAppearance === "hover"
+                ? { ...values, scrollbarAppearance: "auto" }
+                : { ...values };
+        },
+    }),
+    Object.freeze({
+        to: 4,
+        description: "Introduce contextual prompt suggestions with an enabled default.",
+        migrate(values) {
+            return { ...values };
+        },
+    }),
+]);
 export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
     const firstProduced = currentVersion - migrations.length + 1;
     if (migrations.length > 0 && firstProduced < 2) {

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

@@ -1,3 +1,4 @@
+import type { AgentSettingApplicationBoundary, AgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import type { OwnedUiSettingValue } from "./declarations.js";
 import type { OwnedUiSettingsResolution } from "./resolution.js";
 export type OwnedUiSettingsBackend = "a1" | "agent";
@@ -9,8 +10,10 @@ export interface OwnedUiSettingsEntry {
     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. */
+    /** Raw stored value as reported by its backend, for entries the surface can only display. */
     readonly rawValue: unknown;
+    readonly storedValue: unknown;
+    readonly effectiveValue: unknown;
     readonly editable: boolean;
     readonly choices: readonly OwnedUiSettingValue[] | null;
     /** True when the value is a structured object edited through its own surface. */
@@ -26,7 +29,7 @@ export interface OwnedUiSettingsEntry {
         readonly fallback: boolean;
     }[];
     readonly origin: "default" | "stored" | "engine";
-    readonly application: "live" | "restart" | "engine";
+    readonly application: AgentSettingApplicationBoundary;
 }
 export interface OwnedUiSettingsSection {
     readonly id: string;
@@ -38,23 +41,7 @@ export interface OwnedUiSettingsSection {
     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>>;
+    readonly descriptors: readonly AgentSettingDescriptor[];
     /** Whether the engine advertises settings write capability at all. */
     readonly writeAdvertised: boolean;
     /** Set when the engine could not report its settings. */

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

@@ -1,16 +1,19 @@
 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 => ({
+    const grouped = new Map();
+    for (const setting of input.resolution.settings) {
+        const section = setting.declaration.section ?? { id: "a1", title: "A1" };
+        const group = grouped.get(section.id) ?? { title: section.title, entries: [] };
+        group.entries.push({
             id: setting.declaration.id,
-            label: null,
+            label: setting.declaration.label ?? null,
             backend: "a1",
             description: setting.declaration.description,
             value: setting.value,
             rawValue: setting.value,
+            storedValue: setting.value,
+            effectiveValue: setting.value,
             editable: true,
             structured: false,
             minimum: null,
@@ -18,12 +21,28 @@ export function buildOwnedUiSettingsSections(input) {
             flags: [],
             choices: setting.declaration.allowedValues,
             origin: setting.source,
-            application: setting.declaration.application,
-        }))),
+            application: setting.declaration.application === "restart" ? "next-start" : "live",
+        });
+        grouped.set(section.id, group);
+    }
+    const ownedAgentEntries = grouped.get(AGENT_SECTION_ID)?.entries ?? [];
+    grouped.delete(AGENT_SECTION_ID);
+    const ownedSections = [...grouped].map(([id, group]) => ({
+        id,
+        title: group.title,
+        entries: Object.freeze(group.entries),
+        unavailableReason: null,
+        readOnlyReason: null,
+    }));
+    const agent = agentSection(input.agent);
+    // Invariant: presentation grouping does not transfer ownership or engine availability to owned entries.
+    const combinedAgent = ownedAgentEntries.length === 0 ? agent : {
+        ...agent,
+        entries: Object.freeze([...agent.entries, ...ownedAgentEntries]),
         unavailableReason: null,
         readOnlyReason: null,
     };
-    return Object.freeze([ownedSection, agentSection(input.agent)]);
+    return Object.freeze([...ownedSections, combinedAgent]);
 }
 export function findOwnedUiSettingsEntry(sections, id, backend) {
     for (const section of sections) {
@@ -41,10 +60,13 @@ function agentSection(snapshot) {
         return frozenSection(`Agent settings are unavailable: ${snapshot.failure}`, null, []);
     }
     if (snapshot.descriptors.length === 0) {
-        return frozenSection("The agent engine reported no settings", null, []);
+        return { id: AGENT_SECTION_ID, title: "Agent", entries: Object.freeze([]), unavailableReason: null, readOnlyReason: null };
     }
-    const entries = snapshot.descriptors.map(descriptor => {
-        const raw = Object.hasOwn(snapshot.values, descriptor.key) ? snapshot.values[descriptor.key] : null;
+    const presented = snapshot.writeAdvertised
+        ? snapshot.descriptors.filter(descriptor => descriptor.writable && descriptor.available)
+        : [];
+    const entries = presented.map(descriptor => {
+        const raw = descriptor.storedValue;
         return {
             id: descriptor.key,
             label: descriptor.label ?? null,
@@ -52,31 +74,28 @@ function agentSection(snapshot) {
             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,
+            storedValue: descriptor.storedValue,
+            effectiveValue: descriptor.effectiveValue,
+            // Invariant: unavailable and non-writable descriptors are filtered before projection.
+            // Every presented structured value remains editable through its own surface.
+            editable: true,
             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,
+            // Protocol: 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",
+            application: descriptor.application,
         };
     });
-    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,
+        readOnlyReason: null,
     };
 }
 function frozenSection(unavailableReason, readOnlyReason, entries) {

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

@@ -1,44 +1,36 @@
-import type { AgentSettingsPort } from "../agent-engine-contracts/index.js";
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/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 status: "applied" | "deferred" | "unavailable" | "failed";
     readonly applied: boolean;
-    /** True when the value is stored but only takes effect on the next start. */
+    /** Compatibility projection for existing A1 restart-bound declarations. */
     readonly pendingRestart: boolean;
-    /** Present when the change could not be persisted; the surface must not show it as saved. */
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
     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;
+    readonly hiddenAgentSettingIds?: readonly string[];
 }
 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.
- */
+/** Routes every accepted setting change only to its owning backend. */
 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/ui/settings/session.js

@@ -0,0 +1,164 @@
+import { assertAgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
+import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
+/** Routes every accepted setting change only to its owning backend. */
+export class OwnedUiSettingsSession {
+    #store;
+    #agent;
+    #agentProvider;
+    #listeners = new Set();
+    #hiddenAgentSettingIds;
+    #resolution;
+    #agentSnapshot = null;
+    #pending = new Map();
+    #restartEffective = new Map();
+    constructor(options) {
+        this.#store = options.store;
+        this.#agent = options.agent ?? null;
+        this.#agentProvider = options.agentProvider ?? null;
+        this.#hiddenAgentSettingIds = new Set(options.hiddenAgentSettingIds ?? []);
+        this.#resolution = options.store.read();
+        for (const setting of this.#resolution.settings) {
+            if (setting.declaration.application === "restart")
+                this.#restartEffective.set(setting.declaration.id, setting.value);
+        }
+    }
+    get resolution() {
+        return this.#resolution;
+    }
+    async load() {
+        this.#resolution = this.#store.read();
+        const agent = this.#currentAgent();
+        this.#agentSnapshot = agent === null ? null : await snapshotOf(agent, this.#hiddenAgentSettingIds);
+        this.#notify();
+    }
+    sections() {
+        return buildOwnedUiSettingsSections({ resolution: this.#resolution, agent: this.#agentSnapshot }).map(section => ({
+            ...section,
+            entries: section.entries.map(entry => entry.backend === "a1" && this.#restartEffective.has(entry.id)
+                ? { ...entry, effectiveValue: this.#restartEffective.get(entry.id) }
+                : entry),
+        }));
+    }
+    value(id) {
+        return this.#restartEffective.get(id) ?? this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
+    }
+    pendingValue(id) {
+        return this.#pending.get(id) ?? null;
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async changeStructured(backend, id, value) {
+        if (backend !== "agent")
+            return failed("only an agent setting holds a structured value");
+        return await this.#changeAgentValue(id, value);
+    }
+    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.#changeAgentValue(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 previousSetting = previous.settings.find(setting => setting.declaration.id === id);
+        if (previousSetting?.declaration.application === "restart") {
+            this.#pending.set(id, value);
+            this.#notify();
+            return changed("deferred", "next-start", value, this.#restartEffective.get(id));
+        }
+        this.#pending.delete(id);
+        this.#notify();
+        return changed("applied", "live", value, value);
+    }
+    async #changeAgentValue(id, value) {
+        const agent = this.#currentAgent();
+        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");
+        }
+        let result;
+        try {
+            // Invariant: the coordinator behind the port owns effect installation, persistence,
+            // flush, and rollback. A second surface-level flush would split authority.
+            result = await agent.writeSetting(id, value);
+        }
+        catch (error) {
+            return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
+        }
+        this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
+        this.#notify();
+        return fromAgentOutcome(result);
+    }
+    #currentAgent() {
+        return this.#agentProvider === null ? this.#agent : this.#agentProvider();
+    }
+    #notify() {
+        for (const listener of this.#listeners)
+            listener(this);
+    }
+}
+async function snapshotOf(agent, hidden) {
+    try {
+        const listed = await agent.listSettings();
+        for (const descriptor of listed)
+            assertAgentSettingDescriptor(descriptor);
+        const writeAdvertised = agent.capabilities.write && typeof agent.writeSetting === "function";
+        const descriptors = listed.filter(descriptor => !hidden.has(descriptor.key) && writeAdvertised && descriptor.writable && descriptor.available);
+        return {
+            descriptors,
+            writeAdvertised,
+            failure: null,
+        };
+    }
+    catch (error) {
+        return { descriptors: [], writeAdvertised: false, failure: describe(error) };
+    }
+}
+function failed(failure) {
+    return {
+        status: "failed",
+        applied: false,
+        pendingRestart: false,
+        application: null,
+        storedValue: null,
+        effectiveValue: null,
+        limitationReason: null,
+        failure,
+    };
+}
+function changed(status, application, storedValue, effectiveValue) {
+    return {
+        status,
+        applied: status === "applied",
+        pendingRestart: status === "deferred" && application === "next-start",
+        application,
+        storedValue,
+        effectiveValue,
+        limitationReason: null,
+        failure: null,
+    };
+}
+function fromAgentOutcome(result) {
+    return {
+        status: result.status,
+        applied: result.status === "applied",
+        pendingRestart: result.status === "deferred" && result.application === "next-start",
+        application: result.application,
+        storedValue: result.storedValue,
+        effectiveValue: result.effectiveValue,
+        limitationReason: result.limitationReason,
+        failure: result.failure,
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}