@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/dist/integrations/pi/engine/session-runtime.js

@@ -0,0 +1,412 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { observeCompactionProgress } from "./compaction-progress.js";
+import { createPiRuntimeIntegration } from "./runtime-integration.js";
+import { PiSessionCommandIntegration } from "./session-integration.js";
+import { DefaultPackageManager, VERSION } from "../startup-public.js";
+import { readPullRequest, } from "./repository-pr.js";
+const execFileAsync = promisify(execFile);
+const PULL_REQUEST_REFRESH_MS = 60_000;
+const REPOSITORY_CONTEXT_POLL_MS = 5_000;
+const GIT_BRANCH_TIMEOUT_MS = 5_000;
+const GIT_BRANCH_MAX_BUFFER_BYTES = 4 * 1024;
+/**
+ * The pinned Pi runtime and the session bound to it: creation through the runtime factory, the
+ * session generation that stamps and invalidates events, the subscription that forwards session
+ * events, compaction progress observation, the queued-input integration, and disposal order. The
+ * adapter derives its view state from the session it is handed and never touches these directly.
+ */
+export class PiEngineRuntime {
+    #options;
+    #ports;
+    #runtimeFactory;
+    #checkPackageUpdates;
+    #pullRequestProbe;
+    #pullRequestRefreshMs;
+    #repositoryContextPollMs;
+    #repositoryContextReader;
+    #gitBranchReader;
+    #cwd;
+    #runtime;
+    #session;
+    #unsubscribe;
+    #sessionGeneration = 0;
+    #sessionBindingGeneration = 0;
+    #sessionCommands;
+    #compactionProgress = null;
+    #repositoryCwd;
+    #gitBranch = null;
+    #pullRequest = null;
+    #repositoryRefreshTimer;
+    #repositoryRefreshAbort;
+    #repositoryRefreshTask;
+    #repositoryRefreshPending = false;
+    #lastPullRequestProbeAt = null;
+    #repositoryRefreshEnabled = false;
+    #disposed = false;
+    constructor(options, ports) {
+        this.#options = options;
+        this.#ports = ports;
+        this.#cwd = options.cwd;
+        this.#repositoryCwd = options.cwd;
+        this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
+        this.#checkPackageUpdates = options.checkPackageUpdates
+            ?? (options.createRuntime
+                ? async () => []
+                : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, options.agentDir, settingsManager));
+        this.#pullRequestProbe = options.pullRequestProbe ?? readPullRequest;
+        this.#pullRequestRefreshMs = options.pullRequestRefreshMs ?? PULL_REQUEST_REFRESH_MS;
+        this.#repositoryContextPollMs = options.repositoryContextPollMs ?? REPOSITORY_CONTEXT_POLL_MS;
+        this.#repositoryContextReader = options.repositoryContextReader ?? (async () => null);
+        this.#gitBranchReader = options.gitBranchReader ?? readGitBranch;
+    }
+    get runtime() {
+        return this.#runtime;
+    }
+    get session() {
+        return this.#session;
+    }
+    /** Bumped on every bind and on overload recovery; events from an earlier generation are invalid. */
+    get generation() {
+        return this.#sessionGeneration;
+    }
+    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
+    get bindingGeneration() {
+        return this.#sessionBindingGeneration;
+    }
+    get cwd() {
+        return this.#runtime?.cwd ?? this.#cwd;
+    }
+    get repositoryCwd() {
+        return this.#repositoryCwd;
+    }
+    get gitBranch() {
+        return this.#gitBranch;
+    }
+    get pullRequest() {
+        return this.#pullRequest;
+    }
+    get sessionCommands() {
+        return this.#sessionCommands;
+    }
+    get started() {
+        return this.#runtime !== undefined;
+    }
+    /** Create the runtime, bind its first session, and announce the changelog; startup failures propagate. */
+    async start() {
+        const runtime = await this.#runtimeFactory({
+            cwd: this.#cwd,
+            agentDir: this.#options.agentDir,
+            sessionId: this.#options.sessionId,
+            ...(this.#options.sessionPath === undefined ? {} : { sessionPath: this.#options.sessionPath }),
+            ...(this.#options.sessionSelection === undefined ? {} : { sessionSelection: this.#options.sessionSelection }),
+            ...(this.#options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: this.#options.sessionForkPrompt }),
+            ...(this.#options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: this.#options.projectTrustPrompt }),
+        });
+        this.#runtime = runtime;
+        this.#cwd = runtime.cwd ?? this.#cwd;
+        this.#repositoryCwd = this.#cwd;
+        this.#ports.started(runtime);
+        runtime.setRebindSession(async (session) => {
+            if (this.#ports.rebindBlocked())
+                return;
+            this.bindSession(session);
+            this.#ports.rebound();
+        });
+        for (const diagnostic of [...runtime.diagnostics, ...runtime.services.diagnostics]) {
+            this.#ports.diagnostic(diagnostic.type === "error" ? "error" : diagnostic.type === "warning" ? "warning" : "info", "engine-startup", diagnostic.message, diagnostic.type !== "error");
+        }
+        this.bindSession(runtime.session);
+        await this.#announceChangelog(runtime.services.settingsManager);
+        this.#repositoryRefreshEnabled = true;
+        this.#startRepositoryRefresh();
+        return runtime;
+    }
+    /** Probe extension packages for updates after startup and report them as an informational diagnostic. */
+    async announcePackageUpdates() {
+        const runtime = this.#runtime;
+        if (process.env.PI_OFFLINE || runtime === undefined)
+            return;
+        let updates;
+        try {
+            updates = await this.#checkPackageUpdates(runtime.services.settingsManager);
+        }
+        catch {
+            return;
+        }
+        if (this.#ports.disposed() || updates.length === 0)
+            return;
+        const packages = updates.map(name => `- ${name}`).join("\n");
+        this.#ports.diagnostic("info", "package-updates", `Package updates are available. Run ${PRODUCT_IDENTITY.commandName} pi update --extensions\nPackages:\n${packages}`, true);
+        this.#ports.emitView();
+    }
+    currentSessionFile() {
+        const value = this.#session?.sessionManager?.getSessionFile?.();
+        return typeof value === "string" && value.length > 0 ? value : null;
+    }
+    currentSessionResumeMetadata() {
+        const manager = this.#session?.sessionManager;
+        if (manager === undefined
+            || typeof manager.isPersisted !== "function"
+            || typeof manager.getSessionId !== "function"
+            || typeof manager.getSessionDir !== "function"
+            || typeof manager.usesDefaultSessionDir !== "function"
+            || manager.isPersisted() !== true
+            || !existsSync(this.currentSessionFile() ?? ""))
+            return null;
+        const sessionId = manager.getSessionId();
+        const sessionDir = manager.getSessionDir();
+        if (!sessionId || !sessionDir)
+            return null;
+        return { sessionId, sessionDir, usesDefaultSessionDir: manager.usesDefaultSessionDir() };
+    }
+    /** Replace the bound session under a new generation and subscribe to its events. */
+    bindSession(session) {
+        this.#unsubscribe?.();
+        this.#ports.sessionReplacing();
+        this.#sessionGeneration += 1;
+        this.#sessionBindingGeneration += 1;
+        this.#session = session;
+        this.#sessionCommands = new PiSessionCommandIntegration(session);
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = observeCompactionProgress(session, percent => {
+            if (this.#session === session && !this.#ports.disposed())
+                this.#ports.compactionProgress(percent);
+        });
+        // Invariant: the subscription is live before the adapter rebuilds its state so the extension
+        // rebind that finishes the rebuild cannot emit an event nobody is listening to.
+        this.#subscribe();
+        this.#resetRepositoryRefresh();
+        this.#ports.sessionReplaced(session);
+        if (this.#repositoryRefreshEnabled)
+            this.#startRepositoryRefresh();
+    }
+    /** Stop forwarding the current session's events and open a new generation; overload recovery resumes or abandons it. */
+    suspend() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = null;
+        ++this.#sessionGeneration;
+    }
+    /** Forward the current session's events again under the current generation. */
+    resume() {
+        if (this.#session === undefined)
+            return;
+        this.#subscribe();
+    }
+    compactionStarted() {
+        this.#compactionProgress?.begin();
+    }
+    compactionEnded() {
+        this.#compactionProgress?.end();
+    }
+    // Rationale: a manual compaction ends with an idle session, so the engine would never consume
+    // the messages queued during it; automatic compaction returns to a run or a pending prompt.
+    deliverQueuedAfterCompaction() {
+        const commands = this.#sessionCommands;
+        const generation = this.#sessionGeneration;
+        if (commands === undefined)
+            return;
+        const report = (error) => {
+            if (generation !== this.#sessionGeneration || this.#ports.disposed())
+                return;
+            this.#ports.diagnostic("error", "engine-command", `Queued input could not be sent after compaction: ${error instanceof Error ? error.message : String(error)}`, true);
+            this.#ports.emitView();
+        };
+        commands.deliverQueuedAfterCompaction(report).catch(report);
+    }
+    /** Unsubscribe, stop observing compaction, and dispose the runtime; the session reference is kept for final reads. */
+    async dispose() {
+        this.#disposed = true;
+        this.#repositoryRefreshEnabled = false;
+        if (this.#repositoryRefreshTimer !== undefined)
+            clearTimeout(this.#repositoryRefreshTimer);
+        this.#repositoryRefreshTimer = undefined;
+        this.#repositoryRefreshPending = false;
+        this.#repositoryRefreshAbort?.abort();
+        const repositoryRefreshTask = this.#repositoryRefreshTask;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = null;
+        await repositoryRefreshTask;
+        await this.#runtime?.dispose();
+    }
+    #startRepositoryRefresh() {
+        if (!this.#repositoryRefreshEnabled || this.#disposed || this.#ports.disposed())
+            return;
+        if (this.#repositoryRefreshTask !== undefined) {
+            this.#repositoryRefreshPending = true;
+            return;
+        }
+        const task = this.#refreshRepositoryMetadata();
+        this.#repositoryRefreshTask = task;
+        const settled = () => {
+            if (this.#repositoryRefreshTask === task)
+                this.#repositoryRefreshTask = undefined;
+            if (!this.#repositoryRefreshPending)
+                return;
+            this.#repositoryRefreshPending = false;
+            this.#startRepositoryRefresh();
+        };
+        void task.then(settled, settled);
+    }
+    #resetRepositoryRefresh() {
+        if (this.#repositoryRefreshTimer !== undefined)
+            clearTimeout(this.#repositoryRefreshTimer);
+        this.#repositoryRefreshTimer = undefined;
+        this.#repositoryRefreshAbort?.abort();
+        this.#repositoryCwd = this.#cwd;
+        this.#gitBranch = null;
+        this.#pullRequest = null;
+        this.#lastPullRequestProbeAt = null;
+    }
+    async #refreshRepositoryMetadata() {
+        if (this.#repositoryRefreshAbort !== undefined || this.#disposed || this.#ports.disposed())
+            return;
+        const controller = new AbortController();
+        const generation = this.#sessionBindingGeneration;
+        this.#repositoryRefreshAbort = controller;
+        let associatedContext = null;
+        const manager = this.#session?.sessionManager;
+        const sessionId = manager?.getSessionId?.();
+        const sessionFile = manager?.getSessionFile?.();
+        try {
+            if (typeof sessionId === "string" && sessionId.length > 0 && typeof sessionFile === "string" && sessionFile.length > 0) {
+                try {
+                    associatedContext = await this.#repositoryContextReader(sessionId, sessionFile, controller.signal);
+                }
+                catch {
+                    associatedContext = null;
+                }
+            }
+            const nextCwd = associatedContext?.cwd ?? this.#cwd;
+            let nextBranch = associatedContext?.branch ?? null;
+            if (associatedContext === null) {
+                try {
+                    nextBranch = await this.#gitBranchReader(nextCwd, controller.signal);
+                }
+                catch {
+                    nextBranch = null;
+                }
+            }
+            const metadataChanged = nextCwd !== this.#repositoryCwd || nextBranch !== this.#gitBranch;
+            const remoteDue = metadataChanged || this.#lastPullRequestProbeAt === null
+                || Date.now() - this.#lastPullRequestProbeAt >= this.#pullRequestRefreshMs;
+            if (remoteDue) {
+                let nextPullRequest = null;
+                try {
+                    nextPullRequest = nextBranch === null
+                        ? null
+                        : await this.#pullRequestProbe(nextCwd, nextBranch, controller.signal);
+                }
+                catch {
+                    nextPullRequest = null;
+                }
+                if (controller.signal.aborted || generation !== this.#sessionBindingGeneration || this.#disposed || this.#ports.disposed())
+                    return;
+                const changed = nextCwd !== this.#repositoryCwd
+                    || nextBranch !== this.#gitBranch
+                    || !samePullRequest(this.#pullRequest, nextPullRequest);
+                this.#repositoryCwd = nextCwd;
+                this.#gitBranch = nextBranch;
+                this.#pullRequest = nextPullRequest;
+                this.#lastPullRequestProbeAt = Date.now();
+                if (changed)
+                    this.#ports.emitView();
+            }
+        }
+        catch {
+            if (!controller.signal.aborted && generation === this.#sessionBindingGeneration && !this.#disposed && !this.#ports.disposed()) {
+                const changed = this.#repositoryCwd !== this.#cwd || this.#gitBranch !== null || this.#pullRequest !== null;
+                this.#repositoryCwd = this.#cwd;
+                this.#gitBranch = null;
+                this.#pullRequest = null;
+                this.#lastPullRequestProbeAt = Date.now();
+                if (changed)
+                    this.#ports.emitView();
+            }
+        }
+        finally {
+            if (this.#repositoryRefreshAbort === controller)
+                this.#repositoryRefreshAbort = undefined;
+        }
+        if (controller.signal.aborted || generation !== this.#sessionBindingGeneration || this.#disposed || this.#ports.disposed())
+            return;
+        this.#repositoryRefreshTimer = setTimeout(() => {
+            this.#repositoryRefreshTimer = undefined;
+            this.#startRepositoryRefresh();
+        }, this.#repositoryContextPollMs);
+        this.#repositoryRefreshTimer.unref?.();
+    }
+    #subscribe() {
+        const session = this.#session;
+        if (session === undefined)
+            return;
+        const generation = this.#sessionGeneration;
+        this.#unsubscribe = session.subscribe(event => {
+            if (generation === this.#sessionGeneration && !this.#ports.disposed())
+                this.#ports.event(event);
+        });
+    }
+    async #announceChangelog(settingsManager) {
+        if (!settingsManager || typeof settingsManager.getLastChangelogVersion !== "function"
+            || typeof settingsManager.setLastChangelogVersion !== "function")
+            return;
+        if ((this.#session?.messages.length ?? 0) > 0)
+            return;
+        const lastVersion = settingsManager.getLastChangelogVersion();
+        if (lastVersion === VERSION)
+            return;
+        if (!lastVersion) {
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
+            return;
+        }
+        const markdown = await this.#options.host.readChangelog(lastVersion).catch(() => "");
+        if (markdown.trim().length > 0) {
+            this.#ports.diagnostic("info", settingsManager.getCollapseChangelog() ? "changelog-collapsed" : "changelog-expanded", markdown, true);
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
+        }
+    }
+}
+async function createDefaultPiRuntime(input) {
+    return createPiRuntimeIntegration({
+        cwd: input.cwd,
+        agentDir: input.agentDir,
+        ...(input.sessionPath === undefined ? {} : { sessionPath: input.sessionPath }),
+        ...(input.sessionSelection === undefined ? {} : { sessionSelection: input.sessionSelection }),
+        ...(input.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: input.sessionForkPrompt }),
+        ...(input.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: input.projectTrustPrompt }),
+    });
+}
+async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const updates = await packageManager.checkForAvailableUpdates();
+    return updates.map(update => update.displayName);
+}
+function samePullRequest(left, right) {
+    return left?.number === right?.number && left?.url === right?.url;
+}
+async function readGitBranch(cwd, signal) {
+    if (!existsSync(cwd))
+        return null;
+    try {
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+            cwd,
+            windowsHide: true,
+            timeout: GIT_BRANCH_TIMEOUT_MS,
+            maxBuffer: GIT_BRANCH_MAX_BUFFER_BYTES,
+            signal,
+            encoding: "utf8",
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/integrations/pi/engine/session-selection.d.ts

@@ -0,0 +1,28 @@
+import { SessionManager, type SessionInfo } from "../startup-public.js";
+export interface PiSessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+export type PiSessionForkPrompt = (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export declare class PiSessionSelectionError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+interface SessionSelectionOptions {
+    readonly cwd: string;
+    readonly selection: PiSessionSelection;
+    readonly sessionDir?: string;
+    readonly forkPrompt?: PiSessionForkPrompt;
+    /** Public API seam for deterministic lookup/open race and listing-order evidence. */
+    readonly sessions?: Pick<typeof SessionManager, "list" | "open" | "forkFrom"> & {
+        readonly listAll: (sessionDir?: string) => Promise<SessionInfo[]>;
+    };
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export declare function openSelectedPiSession(options: SessionSelectionOptions): Promise<SessionManager>;
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export declare function resolveSessionArgumentPath(path: string, cwd: string): string;
+export {};

package/dist/integrations/pi/engine/session-selection.js

@@ -0,0 +1,90 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { SessionManager } from "../startup-public.js";
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export class PiSessionSelectionError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "PiSessionSelectionError";
+    }
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export async function openSelectedPiSession(options) {
+    try {
+        const sessions = options.sessions ?? SessionManager;
+        const cwd = resolve(options.cwd);
+        const directory = options.selection.sessionDir ?? options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+        const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, cwd);
+        const target = options.selection.target;
+        let path;
+        let global;
+        if (target.includes("/") || target.includes("\\") || target.endsWith(".jsonl")) {
+            path = resolveSessionArgumentPath(target, cwd);
+        }
+        else {
+            const local = matchSession(await sessions.list(cwd, sessionDir), target);
+            const globalMatch = local ? undefined : matchSession(await sessions.listAll(sessionDir), target);
+            // Compatibility: macOS may expose one temporary directory as /var to one process
+            // and /private/var to another. Physical path identity must not turn that alias into
+            // a cross-project fork prompt.
+            global = globalMatch && !sameProjectDirectory(globalMatch.cwd, cwd) ? globalMatch : undefined;
+            const matched = local ?? globalMatch;
+            if (!matched)
+                throw new PiSessionSelectionError(`No session found matching '${target}'`);
+            path = matched.path;
+        }
+        assertResumeFile(path);
+        if (global) {
+            if (!options.forkPrompt || !await options.forkPrompt({ sourceCwd: global.cwd })) {
+                throw new PiSessionSelectionError("Session resume cancelled.", 0);
+            }
+            assertResumeFile(path);
+            assertCwd(cwd);
+            return sessions.forkFrom(path, cwd, sessionDir);
+        }
+        // Invariant: no await between the final guard and SDK open. A disappeared target
+        // can otherwise produce a new in-memory header instead of an existing session.
+        const manager = sessions.open(path, sessionDir);
+        assertResumeFile(path);
+        assertCwd(manager.getCwd());
+        return manager;
+    }
+    catch (error) {
+        if (error instanceof PiSessionSelectionError)
+            throw error;
+        throw new PiSessionSelectionError(`Could not resume session: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function sameProjectDirectory(left, right) {
+    try {
+        const first = realpathSync.native(resolve(left));
+        const second = realpathSync.native(resolve(right));
+        return process.platform === "win32" ? first.toLowerCase() === second.toLowerCase() : first === second;
+    }
+    catch {
+        return resolve(left) === resolve(right);
+    }
+}
+function matchSession(sessions, target) {
+    return sessions.find(session => session.id === target) ?? sessions.find(session => session.id.startsWith(target));
+}
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export function resolveSessionArgumentPath(path, cwd) {
+    const expanded = path === "~" ? homedir() : /^~[/\\]/.test(path) ? resolve(homedir(), path.slice(2)) : path;
+    return resolve(cwd, expanded);
+}
+function assertResumeFile(path) {
+    if (!existsSync(path))
+        throw new PiSessionSelectionError(`Session file does not exist: ${path}`);
+    const metadata = statSync(path);
+    if (!metadata.isFile() || metadata.size === 0)
+        throw new PiSessionSelectionError(`Session file is empty or not a regular file: ${path}`);
+    accessSync(path, constants.R_OK);
+}
+function assertCwd(cwd) {
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new PiSessionSelectionError(`Session working directory does not exist: ${cwd}`);
+}

package/dist/integrations/pi/engine/settings-bridge.d.ts

@@ -0,0 +1,121 @@
+import type { SettingsManager } from "../startup-public.js";
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingChangeOutcome, AgentSettingDescriptor, AgentSettingOwner, AgentSettingsPort } from "../../../contracts/agent-engine/index.js";
+export type PiSettingKey = "autoCompact" | "showImages" | "imageWidthCells" | "autoResizeImages" | "blockImages" | "enableSkillCommands" | "steeringMode" | "followUpMode" | "transport" | "httpIdleTimeoutMs" | "cacheWarmingMode" | "modelThinkingLevels" | "theme" | "hideThinkingBlock" | "mermaidRenderingMode" | "showCacheMissNotices" | "collapseChangelog" | "enableInstallTelemetry" | "quietStartup" | "defaultProjectTrust" | "doubleEscapeAction" | "treeFilterMode" | "showHardwareCursor" | "editorPaddingX" | "outputPad" | "autocompleteMaxVisible" | "clearOnShrink" | "showTerminalProgress" | "tuiMode" | "fullscreenExitOutput" | "fullscreenScrollbar" | "fullscreenCopyOnSelect" | "warnings";
+export type PiSettingVisualClass = "none" | "transcript" | "transcript-geometry" | "editor-menu" | "queue-transcript" | "status-error" | "retry-error" | "footer-transcript" | "markdown" | "transcript-notice" | "startup-transcript" | "startup-selector" | "selector" | "terminal-cursor" | "editor-geometry" | "menu-geometry" | "terminal-frame" | "terminal-status" | "hidden";
+export interface PiSettingVisualEvidence {
+    /** Reviewed visual family; `none` still names the behavior that can emit styled diagnostics. */
+    readonly class: PiSettingVisualClass;
+    /** Pinned component, lifecycle, or provider-visible failure surface used as the visual authority. */
+    readonly pinnedSurface: string;
+    /** Independent pinned/A1 test or physical checkpoint that owns acceptance. */
+    readonly evidence: string;
+}
+export interface PiSettingEffectDefinition {
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly visual: PiSettingVisualEvidence;
+    /** Bare A1 deliberately replaces this Pi behavior, so its settings UI omits the entry. */
+    readonly hiddenInBare?: true;
+}
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export declare const PI_SETTING_EFFECTS: Readonly<Record<PiSettingKey, PiSettingEffectDefinition>>;
+export interface PiSettingEffectHandler {
+    /** Install one value in the active owner. Handlers must be idempotent and reversible. */
+    apply(value: AgentJsonValue): void | Promise<void>;
+}
+export type PiSettingOwnerHandlers = Partial<Record<PiSettingKey, PiSettingEffectHandler>>;
+export interface PiSettingStorageOperation {
+    readonly key: PiSettingKey;
+    read(): AgentJsonValue;
+    validate(value: AgentJsonValue): void;
+    write(value: AgentJsonValue): void;
+}
+export interface PiSettingsCoordinatorOptions {
+    readonly productMode?: "bare" | "comparison";
+    readonly flush: () => Promise<void>;
+    readonly drainErrors?: () => readonly {
+        readonly error: Error;
+    }[];
+}
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export declare class PiSettingsCoordinator {
+    #private;
+    constructor(operations: readonly PiSettingStorageOperation[], options: PiSettingsCoordinatorOptions);
+    bindOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    unbindOwner(owner: AgentSettingOwner, keys?: readonly PiSettingKey[]): void;
+    definition(key: PiSettingKey): PiSettingEffectDefinition;
+    storedValue(key: PiSettingKey): AgentJsonValue;
+    effectiveValue(key: PiSettingKey): AgentJsonValue;
+    limitationReason(key: PiSettingKey): string | null;
+    available(key: PiSettingKey): boolean;
+    validate(key: PiSettingKey, value: AgentJsonValue): void;
+    apply(key: PiSettingKey, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    flush(): Promise<void>;
+    rollback(key: PiSettingKey, value: AgentJsonValue): Promise<void>;
+}
+export declare function settingsEffectInventoryDrift(presented: readonly string[], reviewed?: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+    readonly duplicated: readonly string[];
+};
+export declare function settingsVisualInventoryViolations(presented: readonly string[], reviewed?: Readonly<Partial<Record<PiSettingKey, PiSettingEffectDefinition>>>): readonly string[];
+/** Values only the running engine knows. */
+export interface PiSettingsProviders {
+    readonly themes?: () => readonly string[];
+    /** Models a per-model thinking override may name, with the levels each one supports. */
+    readonly models?: () => readonly PiSettingsModelChoice[];
+    readonly productMode?: "bare" | "comparison";
+}
+export interface PiSettingsModelChoice {
+    /** `provider/modelId`, the key the engine stores the override under. */
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+    readonly levels: readonly string[];
+}
+/** The choice that clears a per-model override; the engine then applies its global default. */
+export declare const MODEL_THINKING_DEFAULT = "default";
+export declare const AUTOMATIC_THEME = "automatic";
+interface AutomaticTheme {
+    readonly light: string;
+    readonly dark: string;
+}
+export declare function parseAutomaticTheme(stored: string): AutomaticTheme | null;
+/** The keys the pinned engine presents, in the engine's order, read from the generated metadata. */
+export declare const EXPOSED_SETTING_KEYS: readonly string[];
+export declare function settingsInventoryDrift(presented: readonly string[], mapped: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+};
+/**
+ * The one Pi settings boundary the owned UI reads and writes through: the agent settings
+ * port over the pinned settings manager, backed by the transactional coordinator. The
+ * generated metadata owns presentation while the reviewed effect table owns timing,
+ * availability, owner, and active behavior.
+ */
+export declare class PiSettingsBridge implements AgentSettingsPort {
+    #private;
+    readonly capabilities: {
+        write: boolean;
+        flush: boolean;
+    };
+    private readonly settings;
+    constructor(settings: SettingsManager, providers?: PiSettingsProviders);
+    bindOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    unbindOwner(owner: AgentSettingOwner): void;
+    listSettings(): Promise<readonly AgentSettingDescriptor[]>;
+    readSetting(key: string): Promise<AgentJsonValue | undefined>;
+    writeSetting(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    /** Shared route used by the pinned selector and owned settings surface. */
+    writeSettingNow(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    flush(): Promise<void>;
+}
+/** The engine keys overrides as `provider/modelId`; the model id may itself contain slashes. */
+export declare function splitModelKey(key: string): [provider: string, modelId: string];
+export {};