@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+export { cliCapabilities, isPrereleaseVersion } from "./capabilities.js";
+export type { CliCapabilities } from "./capabilities.js";
+export { cliHelp, cliUsage, dispatchCli, parseCliCommand } from "./dispatch.js";
+export type { CliCommand, CliHandlers, CliOutput, UpdateChannel } from "./dispatch.js";
+export { renderPackageOutcome, runPackageCommand } from "./packages.js";
+export type { PackageCommandEnvironment, PackageCommandRequest, PackageCommandStyle, PackageCommandVerb } from "./packages.js";
+export { runVersionStats } from "./version-stats.js";
+export type { VersionStatsOptions } from "./version-stats.js";

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+export { cliCapabilities, isPrereleaseVersion } from "./capabilities.js";
+export { cliHelp, cliUsage, dispatchCli, parseCliCommand } from "./dispatch.js";
+export { renderPackageOutcome, runPackageCommand } from "./packages.js";
+export { runVersionStats } from "./version-stats.js";

package/dist/cli/package-messages.d.ts

@@ -0,0 +1,27 @@
+import chalk from "chalk";
+/** Supported subset of pinned Pi's package-manager CLI presentation. */
+export type PackageCliVerb = "install" | "remove" | "list" | "update";
+export type PackageCommandNamespace = "direct" | "pi";
+export type PackageSyntaxDiagnostic = {
+    readonly verb: PackageCliVerb;
+    readonly kind: "missing-source";
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unknown-option";
+    readonly value: string;
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unexpected-argument";
+    readonly value: string;
+} | {
+    readonly verb: "update";
+    readonly kind: "conflict";
+    readonly message: string;
+};
+type MessageStyle = Pick<typeof chalk, "red" | "dim" | "bold">;
+export declare function packageCommandUsage(verb: PackageCliVerb, namespace?: PackageCommandNamespace): string;
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export declare function packageCommandHelp(verb: PackageCliVerb, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
+export {};

package/dist/cli/package-messages.js

@@ -0,0 +1,83 @@
+// Provenance: wording/layout adapted from Pi 0.84.2 packages/coding-agent/src/package-manager-cli.ts
+// at 914cf1472e715297caa30db4b9535d534a9eb718 (MIT); grammar is restricted to A1's supported subset.
+import chalk from "chalk";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export function packageCommandUsage(verb, namespace = "pi") {
+    const command = namespace === "direct"
+        ? `${PRODUCT_TEXT.commandName} ${verb}`
+        : `${PRODUCT_TEXT.commandName} pi ${verb}`;
+    if (verb === "install" || verb === "remove")
+        return `${command} <source>`;
+    if (verb === "update" && namespace === "direct") {
+        return `${command} [--develop [preview-or-version]|--models|--extensions|source]`;
+    }
+    if (verb === "update")
+        return `${command} [source|--extensions|--models]`;
+    return command;
+}
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export function renderPackageSyntax(diagnostic, namespace = "pi", style = chalk) {
+    const usage = packageCommandUsage(diagnostic.verb, namespace);
+    let message;
+    if (diagnostic.kind === "unknown-option") {
+        return `${style.red(`Unknown option ${diagnostic.value} for "${diagnostic.verb}".`)}\n`
+            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} help" or "${usage}".`)}\n`;
+    }
+    if (diagnostic.kind === "missing-source")
+        message = `Missing ${diagnostic.verb} source.`;
+    else if (diagnostic.kind === "unexpected-argument")
+        message = `Unexpected argument ${diagnostic.value}.`;
+    else
+        message = diagnostic.message;
+    return `${style.red(message)}\n${style.dim(`Usage: ${usage}`)}\n`;
+}
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export function packageCommandHelp(verb, namespace = "pi", style = chalk) {
+    const command = namespace === "direct" ? PRODUCT_TEXT.commandName : `${PRODUCT_TEXT.commandName} pi`;
+    const header = verb === "update" && namespace === "direct"
+        ? `${style.bold("Usage:")}\n`
+            + `  ${command} update\n`
+            + `  ${command} update --develop [preview-or-version]\n`
+            + `  ${command} update --models\n`
+            + `  ${command} update --extensions\n`
+            + `  ${command} update <source>\n\n`
+        : `${style.bold("Usage:")}\n  ${packageCommandUsage(verb, namespace)}\n\n`;
+    switch (verb) {
+        case "install":
+            return header + `Install a package and add it to settings.
+
+Examples:
+  ${command} install npm:@foo/bar
+  ${command} install git:github.com/user/repo
+  ${command} install git:git@github.com:user/repo
+  ${command} install https://github.com/user/repo
+  ${command} install ssh://git@github.com/user/repo
+  ${command} install ./local/path
+
+`;
+        case "remove":
+            return header + `Remove a package and its source from settings.
+Alias: ${command} uninstall <source>
+
+Examples:
+  ${command} remove npm:@foo/bar
+  ${command} uninstall npm:@foo/bar
+
+`;
+        case "list":
+            return header + "List installed packages from user settings.\n\n";
+        case "update":
+            return header + `${namespace === "direct" ? "Update A1, installed packages, or model catalogs." : "Update installed packages or model catalogs."}
+
+Options:
+${namespace === "direct" ? "  --develop [target]     Update to the development channel or one preview\n" : ""}  --extensions            Update installed packages only
+  --models                Refresh model catalogs only
+
+Short forms:
+${namespace === "direct" ? `  ${command} update                Update A1 to the stable release\n  ${command} update --develop      Update A1 to the development preview\n` : ""}  ${command} update --extensions   Update installed packages only
+  ${command} update --models       Refresh model catalogs only
+  ${command} update <source>       Update one package
+
+`;
+    }
+}

package/dist/cli/packages.d.ts

@@ -0,0 +1,32 @@
+import { initializeProductProfile } from "../features/launch/index.js";
+import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../contracts/agent-engine/index.js";
+/**
+ * Package commands manage A1's own profile and nothing else, so no request carries
+ * a profile: `update` with no source means every installed package, and refreshing
+ * model catalogs is its own verb rather than a flag the caller has to remember to
+ * check.
+ */
+export type PackageCommandVerb = "install" | "remove" | "list" | "update" | "refresh-models";
+export interface PackageCommandRequest {
+    readonly verb: PackageCommandVerb;
+    readonly source: string | null;
+}
+export interface PackageCommandStyle {
+    readonly dim: (message: string) => string;
+    readonly bold: (message: string) => string;
+    readonly green: (message: string) => string;
+    readonly red: (message: string) => string;
+    readonly yellow: (message: string) => string;
+}
+export interface PackageCommandEnvironment {
+    readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
+    readonly cwd?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+    readonly stderr?: (message: string) => void;
+    readonly initializeProfile?: typeof initializeProductProfile;
+    /** Defaults to Chalk's terminal-aware styles; injectable for transcript tests. */
+    readonly style?: PackageCommandStyle;
+}
+export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, style?: PackageCommandStyle): string;

package/dist/cli/packages.js

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export async function runPackageCommand(request, environment) {
+    const stdout = environment.stdout ?? (message => process.stdout.write(message));
+    const stderr = environment.stderr ?? (message => process.stderr.write(message));
+    const cwd = environment.cwd ?? process.cwd();
+    const processEnvironment = environment.environment ?? process.env;
+    const style = environment.style ?? chalk;
+    const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
+    const profileRoot = configurationRootForProfile("a1", paths);
+    if (profileRoot === null)
+        throw new Error(PRODUCT_TEXT.diagnostic("has no profile root for package commands"));
+    try {
+        await (environment.initializeProfile ?? initializeProductProfile)(profileRoot);
+    }
+    catch (error) {
+        stderr(`${PRODUCT_TEXT.diagnostic(`could not prepare its profile at ${profileRoot}: ${message(error)}`)}\n`);
+        return 1;
+    }
+    const port = environment.createPort({
+        profileRoot,
+        cwd,
+        onProgress: progress => stdout(style.dim(`${progress.message}\n`)),
+        onDiagnostic: diagnostic => {
+            stderr(`${style.yellow(diagnostic.message)}\n`);
+            if (diagnostic.detail)
+                stderr(`${style.dim(diagnostic.detail)}\n`);
+        },
+    });
+    const outcome = await runVerb(port, request);
+    const rendered = renderPackageOutcome(outcome, style);
+    (outcome.status === "completed" ? stdout : stderr)(rendered);
+    return outcome.status === "completed" ? 0 : 1;
+}
+async function runVerb(port, request) {
+    if (request.verb === "list")
+        return await port.list();
+    if (request.verb === "refresh-models")
+        return await port.refreshModels();
+    if (request.verb === "update")
+        return await port.update(request.source ?? undefined);
+    if (request.source === null)
+        throw new Error(PRODUCT_TEXT.diagnostic(`requires a source for ${request.verb}`));
+    return request.verb === "install" ? await port.install(request.source) : await port.remove(request.source);
+}
+export function renderPackageOutcome(outcome, style = chalk) {
+    if (outcome.status === "failed") {
+        const fallback = outcome.operation === "refresh-models" ? "Unknown model catalog refresh error" : "Unknown package command error";
+        return `${style.red(`Error: ${outcome.detail ?? fallback}`)}\n`;
+    }
+    if (outcome.status === "not-found") {
+        return `${style.red(`No matching package found for ${outcome.source ?? "that source"}`)}\n`;
+    }
+    switch (outcome.operation) {
+        case "refresh-models":
+            return `${style.green("Model catalogs refreshed")}\n`;
+        case "install":
+            return `${style.green(`Installed ${outcome.source}`)}\n`;
+        case "remove":
+            return `${style.green(`Removed ${outcome.source}`)}\n`;
+        case "update":
+            return `${style.green(outcome.source === null ? "Updated packages" : `Updated ${outcome.source}`)}\n`;
+        case "list":
+            return renderPackageList(outcome, style);
+    }
+}
+function renderPackageList(outcome, style) {
+    if (outcome.packages.length === 0)
+        return `${style.dim("No packages installed.")}\n`;
+    const lines = [style.bold("User packages:")];
+    for (const entry of outcome.packages) {
+        lines.push(`  ${entry.source}${entry.filtered ? " (filtered)" : ""}`);
+        if (entry.installedPath !== null)
+            lines.push(style.dim(`    ${entry.installedPath}`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function message(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+}

package/dist/cli/session-context.d.ts

@@ -0,0 +1,9 @@
+import { type SessionContextRequest } from "../features/launch/index.js";
+export type { SessionContextRequest } from "../features/launch/index.js";
+export interface SessionContextCommandOptions {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+    readonly stderr?: (message: string) => void;
+}
+/** Apply repository presentation context only when invoked by an active Pi session shell tool. */
+export declare function runSessionContextCommand(request: SessionContextRequest, options?: SessionContextCommandOptions): Promise<number>;

package/dist/cli/session-context.js

@@ -0,0 +1,29 @@
+import { updateSessionRepositoryContext, } from "../features/launch/index.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+/** Apply repository presentation context only when invoked by an active Pi session shell tool. */
+export async function runSessionContextCommand(request, options = {}) {
+    const environment = options.environment ?? process.env;
+    const stdout = options.stdout ?? (message => process.stdout.write(message));
+    const stderr = options.stderr ?? (message => process.stderr.write(message));
+    const identity = readIdentity(environment);
+    if (identity === null) {
+        stderr(`${PRODUCT_TEXT.diagnostic("session context requires an active A1 shell-tool session.")}\n`);
+        return 2;
+    }
+    try {
+        const cwd = await updateSessionRepositoryContext(identity, request);
+        stdout(cwd === null ? "Session worktree context cleared.\n" : `Session worktree context linked: ${cwd}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr(`${PRODUCT_TEXT.diagnostic(`could not update session context: ${error instanceof Error ? error.message : String(error)}`)}\n`);
+        return 1;
+    }
+}
+function readIdentity(environment) {
+    const sessionId = environment.PI_SESSION_ID;
+    const sessionFile = environment.PI_SESSION_FILE;
+    if (!sessionId || !sessionFile)
+        return null;
+    return { sessionId, sessionFile };
+}

package/dist/cli/version-stats.d.ts

@@ -0,0 +1,22 @@
+interface VersionProcessResult {
+    readonly code: number | null;
+    readonly stdout: string;
+}
+type VersionProcessRunner = (command: string, arguments_: readonly string[]) => Promise<VersionProcessResult>;
+type RegistryFetcher = (url: string) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}>;
+interface VersionOutput {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+export interface VersionStatsOptions {
+    readonly packageRoot: string;
+    readonly output?: VersionOutput;
+    readonly runner?: VersionProcessRunner;
+    readonly fetcher?: RegistryFetcher;
+}
+export declare function runVersionStats(options: VersionStatsOptions): Promise<number>;
+export {};

package/dist/cli/version-stats.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import crossSpawn from "cross-spawn";
+import { prerelease, valid as validSemver } from "semver";
+import { PRODUCT_TEXT } from "../product-identity.js";
+const defaultOutput = {
+    stdout(message) { process.stdout.write(message); },
+    stderr(message) { process.stderr.write(message); },
+};
+export async function runVersionStats(options) {
+    const output = options.output ?? defaultOutput;
+    const runner = options.runner ?? createVersionProcessRunner();
+    let installed;
+    try {
+        const manifest = JSON.parse(await readFile(resolve(options.packageRoot, "package.json"), "utf8"));
+        installed = parseVersion(manifest.version, "installed package");
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
+        return 1;
+    }
+    // Compatibility: match Pi's release behavior: stable builds print only their installed version.
+    // Development builds retain channel visibility for preview comparison and updates.
+    if (prerelease(installed) === null) {
+        output.stdout(`${installed}\n`);
+        return 0;
+    }
+    const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
+    output.stdout(`Current: ${installed}\nDevelop: ${remote.develop ?? "unavailable"}\nRelease: ${remote.release ?? "unavailable"}\n`);
+    if (remote.error)
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
+    return 0;
+}
+// Rationale: npm view respects the user's .npmrc registry and proxy, so it stays primary; the direct
+// registry fetch below covers npm CLI versions whose --json output shape we cannot parse.
+async function queryDistTags(runner, fetcher) {
+    const fromNpm = await queryDistTagsViaNpm(runner);
+    if (fromNpm.error === null)
+        return fromNpm;
+    const fromRegistry = await queryDistTagsViaRegistry(fetcher);
+    if (fromRegistry.error === null)
+        return fromRegistry;
+    return unavailable(`${fromNpm.error}; registry fallback failed: ${fromRegistry.error}`);
+}
+async function queryDistTagsViaNpm(runner) {
+    let result;
+    try {
+        result = await runner("npm", ["view", PRODUCT_TEXT.packageName, "dist-tags", "--json"]);
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+    if (result.code !== 0)
+        return unavailable(`npm exited with status ${result.code ?? "unknown"}`);
+    try {
+        const parsed = JSON.parse(result.stdout);
+        // Compatibility: npm 12 wraps `npm view <pkg> dist-tags --json` output in a one-element array; older npm returns the bare object.
+        const metadata = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
+        return parseDistTags(metadata, "npm");
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+async function queryDistTagsViaRegistry(fetcher) {
+    try {
+        const response = await fetcher(`https://registry.npmjs.org/-/package/${encodeURIComponent(PRODUCT_TEXT.packageName)}/dist-tags`);
+        if (!response.ok)
+            return unavailable(`registry responded with status ${response.status}`);
+        return parseDistTags(JSON.parse(await response.text()), "registry");
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+function parseDistTags(metadata, source) {
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+        return unavailable(`${source} returned a non-object dist-tags value`);
+    }
+    try {
+        const tags = metadata;
+        const release = parseVersion(tags.latest, `${source} latest`);
+        const develop = tags.next === undefined ? null : parseVersion(tags.next, `${source} development channel`);
+        return { release, develop, error: null };
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+function unavailable(error) {
+    return { release: null, develop: null, error };
+}
+const defaultRegistryFetcher = async (url) => await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+function createVersionProcessRunner() {
+    return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {
+        const child = process.platform === "win32"
+            ? crossSpawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] })
+            : spawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] });
+        const stdout = [];
+        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.once("error", rejectPromise);
+        child.once("close", code => resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") }));
+    });
+}
+function parseVersion(value, source) {
+    const parsed = typeof value === "string" ? validSemver(value) : null;
+    if (!parsed)
+        throw new Error(`${source} did not provide a valid semantic version`);
+    return parsed;
+}
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/composition/index.d.ts

@@ -0,0 +1,2 @@
+export { composeOwnedUi, composeOwnedUiApplication, type OwnedUiComposition, type OwnedUiCompositionOptions, } from "./owned-ui.js";
+export { createOwnedRouteHost, type OwnedReferenceProviders, type OwnedReferenceRows } from "./settings-route-host.js";

package/dist/composition/index.js

@@ -0,0 +1,2 @@
+export { composeOwnedUi, composeOwnedUiApplication, } from "./owned-ui.js";
+export { createOwnedRouteHost } from "./settings-route-host.js";

package/dist/composition/owned-ui.d.ts

@@ -0,0 +1,37 @@
+import type { SessionSelection } from "../foundation/lifecycle/session-selection.js";
+import type { PiEngineAdapter } from "../integrations/pi/engine/adapter.js";
+import type { PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/project-trust-preflight.js";
+import type { PiSessionForkPrompt } from "../integrations/pi/engine/session-selection.js";
+import { OwnedSettingsManager } from "../ui/settings/manager.js";
+import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
+export interface OwnedUiCompositionOptions {
+    readonly cwd?: string;
+    readonly terminal?: PresentationTerminalPort;
+    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /** Explicit file selection retained for SDK callers. Public CLI uses sessionSelection. */
+    readonly sessionPath?: string;
+    readonly sessionSelection?: SessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
+    /**
+     * A1 profile whose settings this session reads and writes. Omitted keeps the
+     * session settings-free, which is what the pinned comparison paths use.
+     */
+    readonly profileId?: string;
+    /**
+     * Whether A1's product-specific surfaces are reachable. Comparison profiles
+     * use the same composition with those surfaces withheld.
+     */
+    readonly ownedSurfaces?: "on" | "off";
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+    /** Explicit local diagnostic destination; ignored by comparison/settings-free compositions. */
+    readonly suggestionDiagnosticsPath?: string;
+    /** Optional local metadata-only clipboard diagnostics; never enabled in comparison profiles. */
+    readonly clipboardDiagnosticsPath?: string;
+}
+export interface OwnedUiComposition {
+    readonly application: OwnedUiApplicationPort;
+    /** Present when a profile was supplied, so the caller can resolve settings before start. */
+    readonly settings: OwnedSettingsManager | null;
+}
+export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
+export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;

package/dist/composition/owned-ui.js

@@ -0,0 +1,159 @@
+import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/diagnostics.js";
+import { PRODUCT_IDENTITY } from "../product-identity.js";
+import { PromptHistoryService } from "../features/prompt-history/service.js";
+import { PromptImageSidecar } from "../features/prompt-history/image-sidecar.js";
+import { resolvePromptHistoryPath } from "../features/prompt-history/paths.js";
+import { resolvePromptHistoryDataDir } from "../features/launch/profile-paths.js";
+import { resolveProductPaths } from "../foundation/lifecycle/paths.js";
+import { readSessionRepositoryContext } from "../foundation/lifecycle/session-repository-context.js";
+import { applyConfiguredPiTheme, getAvailablePiThemes } from "../integrations/pi/components/upstream/theme/theme.js";
+import { createPiEngineAdapter } from "../integrations/pi/engine/adapter.js";
+import { ClipboardDiagnosticCapture } from "../app/session-shell/clipboard-diagnostics.js";
+import { OwnedUiSessionShell } from "../app/session-shell/session-shell.js";
+import { OwnedSettingsManager } from "../ui/settings/manager.js";
+import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/presentation-adapter.js";
+import { createOwnedRouteHost } from "./settings-route-host.js";
+import { renderPiShellChangelogLines } from "../integrations/pi/components/shell-presenters-info.js";
+import { readPinnedCommandChangelog } from "../integrations/pi/engine/changelog.js";
+export async function composeOwnedUiApplication(options = {}) {
+    return (await composeOwnedUi(options)).application;
+}
+export async function composeOwnedUi(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const ownedSurfaces = options.ownedSurfaces !== "off";
+    const adapter = options.createPiAdapter
+        ? await options.createPiAdapter()
+        : await createPiEngineAdapter({
+            cwd,
+            availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
+            settingsProductMode: ownedSurfaces ? "bare" : "comparison",
+            ...(ownedSurfaces ? {
+                repositoryContextReader: async (sessionId, sessionFile, signal) => await readSessionRepositoryContext({ sessionId, sessionFile }, { signal }),
+            } : {}),
+            ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+            ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
+            ...(options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: options.sessionForkPrompt }),
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+        });
+    const settings = options.profileId === undefined
+        ? null
+        : new OwnedSettingsManager({
+            configDir: resolveProductPaths().configDir,
+            profileId: options.profileId,
+            agentProvider: () => adapter.settingsPort(),
+        });
+    // Compatibility: bare A1 intentionally ships one visual target while its UI is being completed:
+    // dark, regardless of terminal detection or a previously stored Pi theme. The
+    // comparison profile keeps Pi's configured theme behavior and settings surface.
+    applyConfiguredPiTheme(ownedSurfaces ? "dark" : adapter.configuredTheme());
+    // Rationale: the reference screens read the shell the composition is about to construct; a route
+    // cannot open before the shell exists, so the closure is settled by the time it runs.
+    const references = {
+        changelog: async (input) => {
+            const markdown = input?.document ?? await readPinnedCommandChangelog();
+            return { rows: width => renderPiShellChangelogLines(markdown, width) };
+        },
+        hotkeys: async () => {
+            const presentation = shell.hotkeysPresentation();
+            const { renderPiShellHotkeySections } = await import("../integrations/pi/components/shell-hotkey-sections.js");
+            return { sections: width => renderPiShellHotkeySections(presentation, width) };
+        },
+    };
+    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings, references);
+    const viewportSettings = settings === null || !ownedSurfaces ? null : {
+        snapshot: () => viewportSettingsSnapshot(settings),
+        onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
+    };
+    const diagnosticDestination = options.suggestionDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.suggestionDiagnostics];
+    const suggestionDiagnostics = settings !== null && ownedSurfaces && diagnosticDestination?.trim()
+        ? new SuggestionDiagnosticCapture({ enabled: true, destination: diagnosticDestination }) : null;
+    const promptSuggestions = settings === null || !ownedSurfaces ? null : {
+        ...(suggestionDiagnostics === null ? {} : { diagnostics: suggestionDiagnostics }),
+        generator: adapter,
+        enabled: () => settings.value("promptSuggestions"),
+        onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions"))),
+    };
+    const skills = settings === null || !ownedSurfaces ? null : {
+        presentation: () => settings.value("skillsPresentation"),
+        // Rationale: one listener covers both the A1 presentation choice and the engine skill-command toggle.
+        onChange: (listener) => settings.onChange(() => listener()),
+    };
+    const historyLimit = settings?.value("promptHistoryMaxItems");
+    const historyProfileLocation = settings === null || !ownedSurfaces || !settings.value("promptHistoryEnabled")
+        ? null
+        : resolvePromptHistoryPath(resolvePromptHistoryDataDir(), adapter.agentDir);
+    const promptHistory = historyProfileLocation === null ? null : {
+        limit: typeof historyLimit === "number" ? historyLimit : 100,
+        store: new PromptHistoryService({
+            dataDir: resolvePromptHistoryDataDir(),
+            profileRoot: adapter.agentDir,
+            limit: typeof historyLimit === "number" ? historyLimit : 100,
+        }),
+        imageSidecar: new PromptImageSidecar(historyProfileLocation.imagesDir),
+    };
+    const clipboardDestination = options.clipboardDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.clipboardDiagnostics];
+    const clipboardDiagnostics = settings !== null && ownedSurfaces && clipboardDestination?.trim()
+        ? new ClipboardDiagnosticCapture(clipboardDestination) : null;
+    let shell;
+    try {
+        shell = new OwnedUiSessionShell({
+            engine: {
+                backend: adapter,
+                cwd: adapter.cwd,
+                ...(routeHost === null ? {} : { routeHost }),
+                ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
+            },
+            presentation: {
+                ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+                ...(clipboardDiagnostics === null ? {} : { input: { onEvent: event => clipboardDiagnostics.runtime(event) } }),
+                ...(viewportSettings === null ? {} : { viewportSettings }),
+                ...(settings === null || !ownedSurfaces ? {} : {
+                    quitOutro: { snapshot: () => quitOutroSettingsSnapshot(settings), interactive: process.stdout.isTTY === true },
+                }),
+            },
+            ...(clipboardDiagnostics === null ? {} : { diagnostics: {
+                    responseCopy: { onEvent: event => clipboardDiagnostics.copy(event) },
+                    paste: event => clipboardDiagnostics.paste(event),
+                } }),
+            ...(promptSuggestions === null ? {} : { suggestions: promptSuggestions }),
+            ...(skills === null ? {} : { skills }),
+            ...(promptHistory === null ? {} : { history: {
+                    ...promptHistory,
+                    editor: await import("../integrations/pi/components/history-editor-loader.js").then(module => module.loadHistoryEditor()),
+                } }),
+        });
+    }
+    catch (error) {
+        clipboardDiagnostics?.dispose();
+        suggestionDiagnostics?.dispose();
+        throw error;
+    }
+    const application = {
+        get disposed() { return adapter.disposed; },
+        start: () => shell.start(),
+        flush: () => adapter.flushEvents(),
+        waitUntilStopped: () => shell.waitUntilStopped(),
+        dispose: async () => {
+            try {
+                await shell.dispose();
+            }
+            finally {
+                suggestionDiagnostics?.dispose();
+                clipboardDiagnostics?.dispose();
+            }
+        },
+    };
+    return { application, settings };
+}
+function quitOutroSettingsSnapshot(settings) {
+    return {
+        enabled: settings.value("quitAnimation"),
+    };
+}
+function viewportSettingsSnapshot(settings) {
+    return {
+        scrollbarAppearance: settings.value("scrollbarAppearance"),
+        scrollbarStyle: settings.value("scrollbarStyle"),
+        scrollbarSpeed: settings.value("scrollbarSpeed"),
+    };
+}

package/dist/composition/settings-route-host.d.ts

@@ -0,0 +1,16 @@
+import type { ReferenceDocumentProvider } from "../features/owned-ui/reference-screen-app.js";
+import type { OwnedSettingsManager } from "../ui/settings/manager.js";
+import type { UiRouteHost, UiRouteInput } from "../ui/apps/contracts.js";
+/** Styled document rows for one content width. */
+export type OwnedReferenceRows = NonNullable<ReferenceDocumentProvider["rows"]>;
+/** Documents supplied by composition so the route host never reads shell data itself. */
+export interface OwnedReferenceProviders {
+    changelog(input?: UiRouteInput): Promise<ReferenceDocumentProvider>;
+    hotkeys(): Promise<ReferenceDocumentProvider>;
+}
+/**
+ * Declares the A1-owned settings route, and the changelog and hotkeys reference
+ * routes when their documents are supplied, without evaluating their presentation
+ * graphs during startup. Opening a route retains input while the optional module loads.
+ */
+export declare function createOwnedRouteHost(settings: OwnedSettingsManager, references?: OwnedReferenceProviders): UiRouteHost;