@timurproko/a1 0.2.6-dev.717 → 0.2.6-dev.734

package/dist/integrations/pi/components/upstream/program-status-reporter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Provenance: @earendil-works/pi-coding-agent 1.1.0 (MIT), commit abe508e1b89912adde45528136c3221eb69acdd7,
+ * packages/coding-agent/src/modes/interactive/program-status-reporter.ts.
+ * Modifications: Remap Pi session events to A1's neutral run events, inject the terminal reporter, use
+ * A1's application identity, and clear dialog state when the owned session changes.
+ * Deviations: none.
+ */
+import type { ProgramStatus } from "@earendil-works/pi-tui";
+import type { OwnedUiEvent } from "../../../../contracts/owned-ui/index.js";
+export type ProgramStatusBlocked = {
+    readonly kind: NonNullable<ProgramStatus["kind"]>;
+    readonly message: string;
+};
+type ProgramStatusRunEvent = Extract<OwnedUiEvent, {
+    type: "agent-run-started" | "assistant-message-completed" | "agent-run-settled";
+}>;
+/** Reports A1's owned session lifecycle through Pi TUI's OSC 7501 terminal contract. */
+export declare class ProgramStatusReporter {
+    #private;
+    constructor(reportStatus: (status: ProgramStatus) => void, getSessionName: () => string | undefined, app?: string);
+    handleEvent(event: ProgramStatusRunEvent): void;
+    /** Report `blocked` for a dialog until it is cleared with `undefined`. Reopening a source replaces it. */
+    setBlocked(source: string, status: ProgramStatusBlocked | undefined): void;
+    /** Preserve the first visible error line without exposing transcript or prompt content. */
+    setErrorMessage(message: string | undefined): void;
+    /** Forget the previous session's run and transient dialogs. */
+    reset(): void;
+    clear(): void;
+    report(): void;
+}
+export {};

package/dist/integrations/pi/components/upstream/program-status-reporter.js

@@ -0,0 +1,89 @@
+function firstLine(text) {
+    return text?.split(/\r?\n/, 1)[0]?.trim() || "Error";
+}
+/** Reports A1's owned session lifecycle through Pi TUI's OSC 7501 terminal contract. */
+export class ProgramStatusReporter {
+    #reportStatus;
+    #getSessionName;
+    #app;
+    #runActive = false;
+    #runResult = { state: "done" };
+    #restingStatus = { state: "idle" };
+    #blocked = new Map();
+    #lastReport;
+    constructor(reportStatus, getSessionName, app = "a1") {
+        this.#reportStatus = reportStatus;
+        this.#getSessionName = getSessionName;
+        this.#app = app;
+    }
+    handleEvent(event) {
+        switch (event.type) {
+            case "agent-run-started":
+                this.#runActive = true;
+                this.#runResult = { state: "done" };
+                break;
+            case "assistant-message-completed":
+                this.#runResult = event.successful
+                    ? { state: "done" }
+                    : this.#runResult.state === "error" ? this.#runResult : { state: "error" };
+                break;
+            case "agent-run-settled":
+                this.#runActive = false;
+                this.#restingStatus = event.aborted
+                    ? { state: "idle" }
+                    : event.successful
+                        ? this.#runResult
+                        : this.#runResult.state === "error" ? this.#runResult : { state: "error" };
+                break;
+        }
+        this.report();
+    }
+    /** Report `blocked` for a dialog until it is cleared with `undefined`. Reopening a source replaces it. */
+    setBlocked(source, status) {
+        this.#blocked.delete(source);
+        if (status !== undefined)
+            this.#blocked.set(source, status);
+        this.report();
+    }
+    /** Preserve the first visible error line without exposing transcript or prompt content. */
+    setErrorMessage(message) {
+        const status = { state: "error", message: firstLine(message) };
+        if (this.#runActive)
+            this.#runResult = status;
+        else
+            this.#restingStatus = status;
+        this.report();
+    }
+    /** Forget the previous session's run and transient dialogs. */
+    reset() {
+        this.#runActive = false;
+        this.#runResult = { state: "done" };
+        this.#restingStatus = { state: "idle" };
+        this.#blocked.clear();
+        this.report();
+    }
+    clear() {
+        this.#emit({ state: "clear", app: this.#app });
+    }
+    report() {
+        this.#emit({ ...this.#currentStatus(), app: this.#app });
+    }
+    #emit(status) {
+        const key = JSON.stringify(status);
+        if (key === this.#lastReport)
+            return;
+        this.#lastReport = key;
+        this.#reportStatus(status);
+    }
+    #currentStatus() {
+        const blocked = [...this.#blocked.values()].at(-1);
+        if (blocked !== undefined)
+            return { state: "blocked", ...blocked };
+        const status = this.#runActive ? { state: "working" } : this.#restingStatus;
+        if (status.state === "working" || status.state === "done") {
+            const message = this.#getSessionName();
+            return { ...status, ...(message === undefined ? {} : { message }) };
+        }
+        return status;
+    }
+}

package/dist/integrations/pi/components/upstream/theme/theme-controller.d.ts

@@ -1,5 +1,5 @@
 /**
- * Provenance: @earendil-works/pi-coding-agent 1.0.4 (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df,
+ * Provenance: @earendil-works/pi-coding-agent 1.1.0 (MIT), commit abe508e1b89912adde45528136c3221eb69acdd7,
  * packages/coding-agent/src/modes/interactive/theme/theme-controller.ts.
  * Modifications: Source-synchronized controller port: renamed owner class, injected dependency-free
  * settings/runtime ports, remapped private theme helpers to the public-backed A1 theme adapter, and

package/dist/integrations/pi/components/upstream/theme/theme.d.ts

@@ -1,6 +1,7 @@
 import { Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 export type { ThemeColor } from "@earendil-works/pi-coding-agent";
-import { type RgbColor } from "@earendil-works/pi-tui";
+import { type Color, type RgbColor } from "@earendil-works/pi-tui";
+import type { OwnedUiBackgroundStyle, UiAccentColor } from "../../../../../contracts/owned-ui/index.js";
 export declare const PINNED_PI_LAYOUT: Readonly<{
     readonly editorPaddingX: 0;
     readonly outputPad: 1;
@@ -35,9 +36,29 @@ export interface PiTerminalThemeDetector {
         readonly timeoutMs: number;
     }): Promise<PiTerminalTheme | undefined>;
 }
+export interface PiAccentProjection {
+    readonly accent: Color;
+    readonly border: Color;
+    readonly secondaryHeading: Color;
+    readonly selectedBg: Color;
+    readonly userMessageBg: Color;
+}
+/** Derive the complete semantic family from any primary accent, including future custom colors. */
+export declare function derivePiAccentProjection(accent: Color, appearance: PiTerminalTheme): PiAccentProjection;
 export declare function ensurePiTheme(): Theme;
 export declare function piTheme(): Theme;
 export declare function currentPiThemeName(): string;
+export declare function currentPiAccentColor(): UiAccentColor;
+/** Paints one menu swatch from a named A1 palette entry. */
+export declare function renderPiAccentPreview(color: string, text: string): string | null;
+/** Derives A1's fullscreen canvas without adding a token to Pi's theme grammar. */
+export declare function derivePiCanvasBackground(style: OwnedUiBackgroundStyle, accent: Color): Color | null;
+/** Resolves the selected canvas through the active accent and terminal color mode. */
+export declare function piCanvasBackgroundAnsi(style: OwnedUiBackgroundStyle): string | null;
+/** Keeps the complete comparison theme unmodified while bare A1 projects its semantic accent family. */
+export declare function setPiPackageBorderProjectionEnabled(enabled: boolean): void;
+/** Reprojects the active base theme; repeated changes never derive from an earlier projection. */
+export declare function setPiAccentColor(color: UiAccentColor): void;
 export declare function applyPiTheme(name: string, enableWatcher?: boolean, mode?: PiColorMode): PiThemeResult;
 export declare function applyPiThemeInstance(theme: Theme): PiThemeResult;
 export declare function onPiThemeChange(listener: () => void): () => void;

package/dist/integrations/pi/components/upstream/theme/theme.js

@@ -1,15 +1,16 @@
 /**
- * Provenance: @earendil-works/pi-coding-agent 1.0.4 (MIT), commit 7c10bd4337495ee613f2224843ecdf349b80d1df,
+ * Provenance: @earendil-works/pi-coding-agent 1.1.0 (MIT), commit abe508e1b89912adde45528136c3221eb69acdd7,
  * packages/coding-agent/src/modes/interactive/theme/theme.ts.
  * Modifications: Source-synchronized theme port: retain pinned theme schema, variable/color
  * resolution, built-in and custom loading, terminal detection, and layout defaults while constructing
- * the public package-root Theme class.
- * Deviations: theme-public-api-boundary, theme-owned-watcher-boundary.
+ * the public package-root Theme class, projecting A1's optional semantic accent, and deriving its
+ * owned fullscreen canvas.
+ * Deviations: theme-public-api-boundary, theme-owned-watcher-boundary, semantic-accent-projection.
  */
 import { existsSync, readFileSync, readdirSync, watch } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir, initTheme, Theme, } from "../../../startup-public.js";
-import { getCapabilities } from "@earendil-works/pi-tui";
+import { backgroundAnsi, colorToOkhsl, foregroundAnsi, getCapabilities, okhslColor, } from "@earendil-works/pi-tui";
 import { BUILTIN_THEME_RESOURCES, isBuiltinThemeName } from "../../resources/builtin-themes.js";
 export const PINNED_PI_LAYOUT = Object.freeze({
     editorPaddingX: 0,
@@ -31,12 +32,53 @@ const FOREGROUND_COLORS = [
 const BACKGROUND_COLORS = [
     "selectedBg", "searchMatchBg", "userMessageBg", "customMessageBg", "toolPendingBg", "toolSuccessBg", "toolErrorBg",
 ];
+const ACCENT_PALETTE = Object.freeze({
+    purple: Object.freeze({
+        dark: Object.freeze({ kind: "rgb", r: 167, g: 152, b: 215 }),
+        light: Object.freeze({ kind: "rgb", r: 116, g: 89, b: 180 }),
+    }),
+    blue: Object.freeze({ dark: okhslColor(268, 0.80, 0.67), light: okhslColor(268, 0.90, 0.47) }),
+    cyan: Object.freeze({ dark: okhslColor(202, 0.58, 0.67), light: okhslColor(203, 0.73, 0.46) }),
+    green: Object.freeze({ dark: okhslColor(159, 0.59, 0.67), light: okhslColor(159, 0.75, 0.46) }),
+    orange: Object.freeze({ dark: okhslColor(48, 0.75, 0.67), light: okhslColor(48, 0.90, 0.47) }),
+    pink: Object.freeze({ dark: okhslColor(337, 0.72, 0.67), light: okhslColor(337, 0.75, 0.48) }),
+});
+function clamp(value, minimum, maximum) {
+    return Math.max(minimum, Math.min(maximum, value));
+}
+function wrapHue(hue) {
+    return ((hue % 360) + 360) % 360;
+}
+/** Derive the complete semantic family from any primary accent, including future custom colors. */
+export function derivePiAccentProjection(accent, appearance) {
+    const { h, s, l } = colorToOkhsl(accent);
+    const warm = h < 90 || h >= 270;
+    const magenta = h >= 270 && h < 325;
+    const blue = h >= 210 && h < 270;
+    const borderHue = wrapHue(h + (warm ? -20 : 20));
+    const secondaryHue = wrapHue(h + (magenta ? 55 : blue ? -50 : warm ? 35 : -35));
+    const dark = appearance === "dark";
+    const selectedSaturation = clamp(s * (dark ? 0.25 : 0.16), dark ? 0.10 : 0.08, dark ? 0.16 : 0.11);
+    const selectedLightness = dark ? l * 0.37 : 1 - (1 - l) * 0.075;
+    return Object.freeze({
+        accent,
+        border: okhslColor(borderHue, clamp(s * 0.78, 0.30, 0.64), clamp(l - (dark ? 0.17 : 0.11), 0, 1)),
+        secondaryHeading: okhslColor(secondaryHue, clamp(s + 0.20, 0.62, 0.82), clamp(l + (dark ? 0.09 : -0.09), 0, 1)),
+        selectedBg: okhslColor(h, selectedSaturation, selectedLightness),
+        userMessageBg: okhslColor(h, selectedSaturation * 2 / 3, dark ? l * 0.34 : 1 - (1 - l) * 0.055),
+    });
+}
+let activeBaseTheme;
 let activeTheme;
 let activeThemeName;
 let activeThemeMode;
+let activeAccentColor = "purple";
+let packageBorderProjectionEnabled = true;
 let themeWatcher;
 let themeReloadTimer;
 const themeChangeListeners = new Set();
+const accentProjectionBases = new WeakMap();
+const accentProjectionCache = new WeakMap();
 export function ensurePiTheme() {
     if (activeTheme)
         return activeTheme;
@@ -51,13 +93,65 @@ export function currentPiThemeName() {
     ensurePiTheme();
     return activeThemeName;
 }
+export function currentPiAccentColor() {
+    return activeAccentColor;
+}
+/** Paints one menu swatch from a named A1 palette entry. */
+export function renderPiAccentPreview(color, text) {
+    ensurePiTheme();
+    const base = activeBaseTheme;
+    if (!isAccentColor(color))
+        return null;
+    const accent = ACCENT_PALETTE[color][base.appearance];
+    return `${foregroundAnsi(accent, base.getColorMode())}${text}\u001b[39m`;
+}
+/** Derives A1's fullscreen canvas without adding a token to Pi's theme grammar. */
+export function derivePiCanvasBackground(style, accent) {
+    if (style === "transparent")
+        return null;
+    if (style === "dark")
+        return okhslColor(229, 0.03, 0.12);
+    const { h } = colorToOkhsl(accent);
+    return okhslColor(h, 0.12, 0.12);
+}
+/** Resolves the selected canvas through the active accent and terminal color mode. */
+export function piCanvasBackgroundAnsi(style) {
+    ensurePiTheme();
+    const base = activeBaseTheme;
+    const accent = ACCENT_PALETTE[activeAccentColor][base.appearance];
+    const background = derivePiCanvasBackground(style, accent);
+    return background === null ? null : backgroundAnsi(background, base.getColorMode());
+}
+/** Keeps the complete comparison theme unmodified while bare A1 projects its semantic accent family. */
+export function setPiPackageBorderProjectionEnabled(enabled) {
+    if (packageBorderProjectionEnabled === enabled)
+        return;
+    packageBorderProjectionEnabled = enabled;
+    if (activeBaseTheme !== undefined)
+        activeTheme = resolvePiAccentTheme(activeBaseTheme);
+    syncPiPackageBorderProjection();
+    notifyThemeChanged();
+}
+/** Reprojects the active base theme; repeated changes never derive from an earlier projection. */
+export function setPiAccentColor(color) {
+    if (activeAccentColor === color)
+        return;
+    activeAccentColor = color;
+    if (activeBaseTheme === undefined)
+        return;
+    activeTheme = resolvePiAccentTheme(activeBaseTheme);
+    syncPiPackageBorderProjection();
+    notifyThemeChanged();
+}
 export function applyPiTheme(name, enableWatcher = false, mode) {
     try {
         const loaded = loadPiTheme(name, mode);
         initTheme(name, false);
-        activeTheme = loaded;
+        activeBaseTheme = loaded;
+        activeTheme = resolvePiAccentTheme(loaded);
         activeThemeName = name;
         activeThemeMode = mode;
+        syncPiPackageBorderProjection();
         if (enableWatcher)
             startPiThemeWatcher(name);
         notifyThemeChanged();
@@ -65,18 +159,23 @@ export function applyPiTheme(name, enableWatcher = false, mode) {
     }
     catch (error) {
         initTheme("dark", false);
-        activeTheme = loadPiTheme("dark", mode);
+        activeBaseTheme = loadPiTheme("dark", mode);
+        activeTheme = resolvePiAccentTheme(activeBaseTheme);
         activeThemeName = "dark";
         activeThemeMode = mode;
+        syncPiPackageBorderProjection();
         notifyThemeChanged();
         return { success: false, name: "dark", error: error instanceof Error ? error.message : String(error) };
     }
 }
 export function applyPiThemeInstance(theme) {
     stopPiThemeWatcher();
-    activeTheme = theme;
-    activeThemeName = theme.name ?? "<in-memory>";
-    activeThemeMode = theme.getColorMode();
+    const base = accentProjectionBases.get(theme) ?? theme;
+    activeBaseTheme = base;
+    activeTheme = resolvePiAccentTheme(base);
+    activeThemeName = base.name ?? "<in-memory>";
+    activeThemeMode = base.getColorMode();
+    syncPiPackageBorderProjection();
     notifyThemeChanged();
     return { success: true, name: activeThemeName };
 }
@@ -236,7 +335,9 @@ function startPiThemeWatcher(name) {
             if (activeThemeName !== name || !existsSync(path))
                 return;
             try {
-                activeTheme = loadPiTheme(name, activeThemeMode);
+                activeBaseTheme = loadPiTheme(name, activeThemeMode);
+                activeTheme = resolvePiAccentTheme(activeBaseTheme);
+                syncPiPackageBorderProjection();
                 notifyThemeChanged();
             }
             catch { }
@@ -248,6 +349,120 @@ function notifyThemeChanged() {
     for (const listener of themeChangeListeners)
         listener();
 }
+function resolvePiAccentTheme(base) {
+    const rootBase = accentProjectionBases.get(base) ?? base;
+    return packageBorderProjectionEnabled ? projectPiAccent(rootBase, activeAccentColor) : rootBase;
+}
+function syncPiPackageBorderProjection() {
+    if (activeBaseTheme === undefined || activeTheme === undefined)
+        return;
+    if (!packageBorderProjectionEnabled) {
+        setPiPackageThemeInstance(activeBaseTheme);
+        return;
+    }
+    const base = activeBaseTheme;
+    const projected = activeTheme;
+    setPiPackageThemeInstance(new Proxy(base, {
+        get(target, property) {
+            if (property === "colors")
+                return Object.freeze({ ...target.colors, border: projected.colors.border });
+            if (property === "fg") {
+                return (token, text) => token === "border"
+                    ? projected.fg(token, text)
+                    : target.fg(token, text);
+            }
+            if (property === "getFgAnsi") {
+                return (token) => token === "border"
+                    ? projected.getFgAnsi(token)
+                    : target.getFgAnsi(token);
+            }
+            if (property === "style") {
+                return (text, options) => target.style(text, {
+                    ...options,
+                    ...(options.fg === "border" ? { fg: projected.colors.border } : {}),
+                });
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    }));
+}
+function setPiPackageThemeInstance(theme) {
+    Reflect.set(globalThis, Symbol.for("@earendil-works/pi-coding-agent:theme"), theme);
+    Reflect.set(globalThis, Symbol.for("@mariozechner/pi-coding-agent:theme"), theme);
+}
+function isAccentColor(value) {
+    return Object.hasOwn(ACCENT_PALETTE, value);
+}
+/** A transparent Theme projection keeps every role outside the selected accent family on the base. */
+function projectPiAccent(base, color) {
+    const rootBase = accentProjectionBases.get(base) ?? base;
+    const cached = accentProjectionCache.get(rootBase)?.get(color);
+    if (cached !== undefined)
+        return cached;
+    const tone = derivePiAccentProjection(ACCENT_PALETTE[color][rootBase.appearance], rootBase.appearance);
+    const accentAnsi = foregroundAnsi(tone.accent, rootBase.getColorMode());
+    const foregrounds = Object.freeze({
+        accent: tone.accent,
+        border: tone.border,
+        mdHeading: tone.secondaryHeading,
+        mdListBullet: tone.secondaryHeading,
+    });
+    const foregroundSequences = Object.freeze({
+        accent: accentAnsi,
+        border: foregroundAnsi(tone.border, rootBase.getColorMode()),
+        mdHeading: foregroundAnsi(tone.secondaryHeading, rootBase.getColorMode()),
+        mdListBullet: foregroundAnsi(tone.secondaryHeading, rootBase.getColorMode()),
+    });
+    const backgrounds = Object.freeze({
+        selectedBg: tone.selectedBg,
+        userMessageBg: tone.userMessageBg,
+    });
+    const backgroundSequences = Object.freeze({
+        selectedBg: backgroundAnsi(tone.selectedBg, rootBase.getColorMode()),
+        userMessageBg: backgroundAnsi(tone.userMessageBg, rootBase.getColorMode()),
+    });
+    const projection = new Proxy(rootBase, {
+        get(target, property) {
+            if (property === "colors")
+                return Object.freeze({
+                    ...target.colors,
+                    ...foregrounds,
+                    ...backgrounds,
+                });
+            if (property === "fg") {
+                return (token, text) => foregroundSequences[token] === undefined
+                    ? target.fg(token, text)
+                    : `${foregroundSequences[token]}${text}\u001b[39m`;
+            }
+            if (property === "bg") {
+                return (token, text) => backgroundSequences[token] === undefined
+                    ? target.bg(token, text)
+                    : `${backgroundSequences[token]}${text}\u001b[49m`;
+            }
+            if (property === "getFgAnsi") {
+                return (token) => foregroundSequences[token] ?? target.getFgAnsi(token);
+            }
+            if (property === "getBgAnsi") {
+                return (token) => backgroundSequences[token] ?? target.getBgAnsi(token);
+            }
+            if (property === "style") {
+                return (text, options) => target.style(text, {
+                    ...options,
+                    ...(typeof options.fg === "string" && foregrounds[options.fg] !== undefined ? { fg: foregrounds[options.fg] } : {}),
+                    ...(typeof options.bg === "string" && backgrounds[options.bg] !== undefined ? { bg: backgrounds[options.bg] } : {}),
+                });
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+    accentProjectionBases.set(projection, rootBase);
+    const projections = accentProjectionCache.get(rootBase) ?? new Map();
+    projections.set(color, projection);
+    accentProjectionCache.set(rootBase, projections);
+    return projection;
+}
 function customThemePath(name) {
     return join(getAgentDir(), "themes", `${name}.json`);
 }

package/dist/integrations/pi/engine/adapter.d.ts

@@ -1,5 +1,5 @@
 import { type AgentSession } from "../startup-public.js";
-import { type OwnedUiCommand, type OwnedUiImageAttachment, type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionReasoning, type OwnedUiPromptSuggestionRequest, type OwnedUiPromptSuggestionResult, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../../../contracts/owned-ui/index.js";
+import { type OwnedUiCommand, type OwnedUiExtensionPort, type OwnedUiExtensionUiPort, type OwnedUiImageAttachment, type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionReasoning, type OwnedUiPromptSuggestionRequest, type OwnedUiPromptSuggestionResult, type OwnedUiEvent, type OwnedUiReleaseUpdate, type OwnedUiSessionBackend, type OwnedUiSessionCatalogPort, type OwnedUiSessionIdentityPort, type OwnedUiSessionPort, type OwnedUiSessionSettingsPort, type OwnedUiSessionViewModel, type OwnedUiSnapshot, type OwnedUiWorkflowPort } from "../../../contracts/owned-ui/index.js";
 import type { PiAuthenticationProviderOption, PiBashWorkflowResult, PiModelsContext, PiModelsRefreshResult, PiPinnedSettingsCallback, PiPinnedSettingsSnapshot, PiProjectTrustContext, PiProjectTrustUpdate, PiScopedModelsContext, PiScopedModelsRefreshResult, PiSessionResumeMetadata, PiSessionSelectorContext, PiTreeSelectorContext, PiWorkflowAutocompleteCommand, PiWorkflowHost, PiWorkflowInteractionHost, PiWorkflowOption, PiWorkflowRequest, PiWorkflowResult } from "./workflows.js";
 import type { PiSettingsBridge } from "./settings-bridge.js";
 import type { PiSettingOwnerHandlers } from "./settings-bridge.js";
@@ -10,11 +10,29 @@ import { type AdapterCommandResult } from "./command-dispatch.js";
 import { type OwnedPiVisualExtensionSupport } from "./extension-ui-binding.js";
 import { type OwnedPiExtensionResourceSummary, type OwnedPiResourceSummary } from "./resource-catalog.js";
 import { type PiEnginePackageUpdateProbe, type PiEngineRuntimeFactory, type PiRepositoryContextReader } from "./session-runtime.js";
+import { type PiEngineHostSessionPorts } from "./host-ports.js";
 import { PiWorkflowContexts } from "./workflow-contexts.js";
 export type { OwnedPiExtensionResourceSummary, OwnedPiExtensionSourceSummary, OwnedPiResourceSummary } from "./resource-catalog.js";
 export type { PiEngineRuntimeFactory, PiEngineRuntimeFactoryInput } from "./session-runtime.js";
 export type { AdapterCommandResult } from "./command-dispatch.js";
 export type { OwnedPiVisualExtensionSupport } from "./extension-ui-binding.js";
+/**
+ * The Pi objects pinned selectors and transcript renderers are built from. They are not part of the
+ * session backend contract; only the session presenters owner reads them.
+ */
+export interface PiSessionPresentationSource {
+    pinnedModelSelectorContext(): ReturnType<PiWorkflowContexts["pinnedModelSelectorContext"]>;
+    pinnedSessionSelectorContext(): PiSessionSelectorContext;
+    pinnedTreeSelectorContext(): PiTreeSelectorContext;
+    pinnedMessageRenderer(customType: string): unknown;
+    pinnedToolRenderers(toolName: string): unknown;
+    pinnedShortcutDescriptions(bindings: Parameters<AgentSession["extensionRunner"]["getShortcuts"]>[0]): readonly {
+        readonly key: string;
+        readonly description: string;
+    }[];
+    pinnedSettingsModels(): Pick<PiPinnedSettingsSnapshot, "currentModel" | "availableDefaultModels">;
+    applyPinnedSettingValue(callback: PiPinnedSettingsCallback, value: unknown): Promise<PiWorkflowResult>;
+}
 /** Explicit flush failure when required delivery was interrupted rather than completed. */
 export declare class EngineDeliveryError extends Error {
     constructor();
@@ -22,7 +40,13 @@ export declare class EngineDeliveryError extends Error {
 export interface PiEngineAdapterOptions {
     readonly cwd?: string;
     readonly agentDir?: string;
-    readonly sessionId?: string;
+    /** Unique within the process; the engine host assigns one when the caller has none. */
+    readonly sessionId: string;
+    /**
+     * The process-level host this session belongs to. Absent only for adapters built directly in
+     * tests and tools: then no process dispatcher is installed and nothing is announced.
+     */
+    readonly engineHost?: PiEngineHostSessionPorts;
     readonly sessionPath?: string;
     readonly sessionSelection?: PiSessionSelection;
     readonly sessionForkPrompt?: PiSessionForkPrompt;
@@ -41,14 +65,20 @@ export interface PiEngineAdapterOptions {
      * mode. Returns display names of packages with updates available.
      */
     readonly checkPackageUpdates?: PiEnginePackageUpdateProbe;
-    /** Comparison profiles preserve Pi's startup changelog; bare A1 owns release-note startup. */
-    readonly announceStartupChangelog?: boolean;
     readonly repositoryContextReader?: PiRepositoryContextReader;
 }
-/** Owns the pinned Pi session lifecycle and translates its events into the neutral agent-engine contract. */
-export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGeneratorPort {
+/** Owns the pinned Pi session lifecycle and serves it to the owned shell as the neutral session backend. */
+export declare class PiEngineAdapter implements OwnedUiSessionBackend, OwnedUiPromptSuggestionGeneratorPort {
     #private;
-    constructor(options?: PiEngineAdapterOptions);
+    constructor(options: PiEngineAdapterOptions);
+    get identity(): OwnedUiSessionIdentityPort;
+    get session(): OwnedUiSessionPort;
+    get workflows(): OwnedUiWorkflowPort;
+    get settings(): OwnedUiSessionSettingsPort;
+    get catalog(): OwnedUiSessionCatalogPort;
+    get extensions(): OwnedUiExtensionPort;
+    /** The Pi objects behind pinned selectors and renderers, for the session presenters owner only. */
+    presentationSource(): PiSessionPresentationSource;
     setWorkflowInteractionHost(interaction: PiWorkflowInteractionHost): void;
     get sessionId(): string;
     get sessionGeneration(): number;
@@ -65,14 +95,14 @@ export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGenerator
      * pinned Pi's `Update Available` notice; it arrives whenever the check resolves, so a late
      * result is appended to the transcript like Pi's own fire-and-forget version check.
      */
-    announceReleaseUpdate(release: {
-        readonly version: string;
-        readonly command: string;
-        readonly changelogUrl: string | null;
-    }): void;
+    announceReleaseUpdate(release: OwnedUiReleaseUpdate): void;
     suggestionReasoningPolicy(): OwnedUiPromptSuggestionReasoning;
     generate(request: OwnedUiPromptSuggestionRequest): Promise<OwnedUiPromptSuggestionResult>;
     start(): Promise<OwnedUiSessionViewModel>;
+    /** Announce pinned Pi's changelog since the profile's last seen version; the host calls this once per process. */
+    announceStartupChangelog(): Promise<void>;
+    /** Probe extension packages for updates and announce them; the host calls this once per process. */
+    announcePackageUpdates(): Promise<void>;
     onEvent(listener: (event: OwnedUiEvent) => void): () => void;
     /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
     deliveryDiagnostics(): {
@@ -93,13 +123,11 @@ export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGenerator
     extensionResources(): readonly OwnedPiExtensionResourceSummary[];
     workflowAutocompleteCommands(): readonly PiWorkflowAutocompleteCommand[];
     visualExtensionSupport(): OwnedPiVisualExtensionSupport;
-    bindExtensionUi(ui: unknown, shutdown?: () => void | Promise<void>): Promise<void>;
+    bindExtensionUi(ui: OwnedUiExtensionUiPort, shutdown?: () => void | Promise<void>): Promise<void>;
     unbindExtensionUi(): Promise<void>;
     cycleModelWorkflow(direction: "forward" | "backward"): Promise<PiWorkflowResult>;
-    pinnedModelSelectorContext(): ReturnType<PiWorkflowContexts["pinnedModelSelectorContext"]>;
     pinnedProjectTrustContext(): PiProjectTrustContext;
     persistProjectTrust(updates: readonly PiProjectTrustUpdate[]): void;
-    pinnedSessionSelectorContext(): PiSessionSelectorContext;
     pinnedScopedModelsContext(): PiScopedModelsContext;
     updateScopedModels(enabledModelIds: readonly string[] | null): void;
     persistScopedModels(enabledModelIds: readonly string[] | null): void;
@@ -116,7 +144,6 @@ export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGenerator
     pinnedAmbientAuthentication(selection: string): ReturnType<PiWorkflowContexts["pinnedAmbientAuthentication"]>;
     pinnedLogoutOptions(): Promise<readonly PiAuthenticationProviderOption[]>;
     pinnedForkOptions(): readonly PiWorkflowOption[];
-    pinnedTreeSelectorContext(): PiTreeSelectorContext;
     /** Bind the owned UI's clipboard lifecycle without changing the comparison host. True means acknowledged delivery. */
     bindClipboardWriter(writer: (text: string) => Promise<boolean>): () => void;
     /** Workflow and tree copying share the active owner's write fence and delivery acknowledgment. */
@@ -138,17 +165,10 @@ export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGenerator
     get settingsProductMode(): "bare" | "comparison";
     bindSettingsOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
     pinnedSettingsSnapshot(): PiPinnedSettingsSnapshot;
-    applyPinnedSettingValue(callback: PiPinnedSettingsCallback, value: unknown): Promise<PiWorkflowResult>;
-    pinnedMessageRenderer(customType: string): unknown;
-    pinnedShortcutDescriptions(bindings: Parameters<AgentSession["extensionRunner"]["getShortcuts"]>[0]): readonly {
-        readonly key: string;
-        readonly description: string;
-    }[];
-    pinnedToolRenderers(toolName: string): unknown;
     clearQueuedWorkflows(): readonly string[];
     view(): OwnedUiSessionViewModel;
     snapshot(): OwnedUiSnapshot;
     execute(command: OwnedUiCommand): Promise<AdapterCommandResult>;
     dispose(): Promise<void>;
 }
-export declare function createPiEngineAdapter(options?: PiEngineAdapterOptions): Promise<PiEngineAdapter>;
+export declare function createPiEngineAdapter(options: PiEngineAdapterOptions): Promise<PiEngineAdapter>;