@timurproko/a1 0.2.7-dev.808 → 0.2.7-dev.810

package/README.md

@@ -185,13 +185,15 @@ a1 update npm:pi-mcp-adapter
 
 ## Develop
 
+A source build needs Node.js, npm, git, and Rustup. Windows additionally needs Visual Studio or Visual Studio Build Tools with the **Desktop development with C++** workload, MSVC x64/x86 tools, and a Windows SDK; Visual Studio Code is not required. A1 discovers installed Rustup and Visual Studio tools and initializes them for build children, so Git Bash and ordinary PowerShell do not need manual `PATH` or developer-shell setup. It never installs these tools or accepts their licenses automatically.
+
 Install exact locked dependencies:
 
 ```text
 npm ci
 ```
 
-Compile TypeScript and the process guardian into `dist`:
+Compile TypeScript and the native addons into `dist`:
 
 ```text
 npm run build
@@ -221,7 +223,7 @@ Complete non-physical suite:
 npm run test:full
 ```
 
-Report Node, npm, git, Rust, and dependency readiness:
+Report Node, npm, git, Rust, dependency, and Windows C++ readiness. Missing Windows tools are listed in setup order; after installing them, rerun the same build command:
 
 ```text
 npm run doctor

package/dist/app/session-shell/dialog-coordinator.d.ts

@@ -0,0 +1,42 @@
+import type { OwnedUiCommandResult, OwnedUiDialog } from "../../contracts/owned-ui/index.js";
+import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
+import type { PiShellSelectorOption } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { PiTuiOverlayHandle } from "../../integrations/pi/tui-runtime/contracts.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+import type { OwnedUiSessionShellOptions, OwnedUiSessionShellRoot } from "./session-shell-root.js";
+type StartupRoute = NonNullable<OwnedUiSessionShellOptions["engine"]["startupRoute"]>;
+export interface SessionDialogPorts {
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "running" | "hasOverlay" | "showOverlay" | "openRoute" | "requestRender">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "dismissNotice" | "setInputSurface" | "usesDefaultInputSurface">;
+    readonly routeHost: UiRouteHost | null;
+    readonly disposed: () => boolean;
+    /** A route, or the interrupt chord over it, asked to leave A1. */
+    readonly exit: () => void;
+    /** A rendered route closed itself. */
+    readonly routeClosed?: (route: string) => void;
+    readonly startupRoute?: StartupRoute;
+}
+/**
+ * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
+ * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
+ * clears the same state.
+ */
+export declare class SessionDialogCoordinator {
+    #private;
+    constructor(ports: SessionDialogPorts);
+    /** Clears the replacement input surface a selector put in the dock; the shared close action of every dock selector. */
+    readonly closeInputSurface: () => void;
+    showSelector(title: string, options: readonly PiShellSelectorOption[], onSelect: (id: string) => void, onCancel?: () => void): PiTuiOverlayHandle;
+    /** Mirrors the backend's pending dialog; locally owned routes and selectors are left alone when it has none. */
+    syncBackend(dialog: OwnedUiDialog | null): void;
+    openRoute(route: string, input?: UiRouteInput, onClosed?: () => void | Promise<void>): OwnedUiCommandResult;
+    claimsRoute(name: string): boolean;
+    /** Retains a route requested before the runtime runs; the latest request wins. */
+    retainStartupRoute(route: string): void;
+    /** Opens the retained startup route once no overlay or replacement input surface holds the screen. */
+    presentStartupRoute(): void;
+    /** A replaced session takes its dialog with it; a retained startup route still opens. */
+    onSessionReplaced(): void;
+    dispose(): void;
+}
+export {};

package/dist/app/session-shell/dialog-coordinator.js

@@ -0,0 +1,133 @@
+import { createPiShellDialog, createPiShellSelector } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+const OVERLAY_OPTIONS = { width: "70%", maxHeight: "80%", anchor: "center", inputCoordination: "owned" };
+const STARTUP_ROUTE_RETRY_MS = 25;
+/**
+ * Owns the one modal overlay a session shows at a time, whichever source opened it: an owned route,
+ * a local selector, or a backend dialog. Opening one hides the previous one, and every close path
+ * clears the same state.
+ */
+export class SessionDialogCoordinator {
+    #ports;
+    #handle;
+    #id;
+    #source;
+    #startupRoute;
+    #startupRouteTimer;
+    constructor(ports) {
+        this.#ports = ports;
+        this.#startupRoute = ports.startupRoute;
+    }
+    /** Clears the replacement input surface a selector put in the dock; the shared close action of every dock selector. */
+    closeInputSurface = () => {
+        this.#ports.root.setInputSurface(null);
+        this.#ports.terminal.requestRender();
+    };
+    showSelector(title, options, onSelect, onCancel) {
+        this.#handle?.hide();
+        this.#source = "local";
+        this.#id = undefined;
+        const component = createPiShellSelector({
+            title,
+            options,
+            onSelect: id => {
+                onSelect(id);
+                this.#close();
+            },
+            onCancel: () => {
+                this.#close();
+                onCancel?.();
+            },
+        });
+        const handle = this.#ports.terminal.showOverlay(component, OVERLAY_OPTIONS);
+        this.#handle = handle;
+        return handle;
+    }
+    /** Mirrors the backend's pending dialog; locally owned routes and selectors are left alone when it has none. */
+    syncBackend(dialog) {
+        if (!this.#ports.terminal.running)
+            return;
+        if (dialog === null) {
+            // Invariant: locally owned routes (notably /settings) are independent of backend
+            // lifecycle/status events and remain open while an agent is working.
+            if (this.#source === "backend")
+                this.#close();
+            return;
+        }
+        if (this.#source === "backend" && this.#id === dialog.id)
+            return;
+        this.#handle?.hide();
+        this.#source = "backend";
+        const component = createPiShellDialog(dialog, { onSelect: () => this.#close(), onCancel: () => this.#close() });
+        this.#handle = this.#ports.terminal.showOverlay(component, OVERLAY_OPTIONS);
+        this.#id = dialog.id;
+    }
+    openRoute(route, input, onClosed) {
+        const surface = this.#ports.routeHost?.open(route, input) ?? null;
+        if (surface === null)
+            return { outcome: "failed", diagnostic: `route is unavailable: ${route}` };
+        if (!this.#ports.terminal.running)
+            return { outcome: "failed", diagnostic: "runtime is not active" };
+        this.#ports.root.dismissNotice();
+        this.#handle?.hide();
+        this.#source = "route";
+        const handle = this.#ports.terminal.openRoute(surface, {
+            exit: () => this.#ports.exit(),
+            closed: rendered => {
+                if (this.#handle === handle)
+                    this.#clear();
+                if (rendered) {
+                    try {
+                        void onClosed?.()?.catch(() => undefined);
+                    }
+                    catch { /* Rationale: a failed acknowledgement stays pending. */ }
+                    this.#ports.routeClosed?.(route);
+                }
+            },
+        });
+        this.#handle = handle;
+        this.#id = surface.id;
+        return { outcome: "completed", diagnostic: null };
+    }
+    claimsRoute(name) {
+        return this.#ports.routeHost?.claims(name) ?? false;
+    }
+    /** Retains a route requested before the runtime runs; the latest request wins. */
+    retainStartupRoute(route) {
+        this.#startupRoute = { route };
+    }
+    /** Opens the retained startup route once no overlay or replacement input surface holds the screen. */
+    presentStartupRoute() {
+        const pending = this.#startupRoute;
+        if (pending === undefined || this.#ports.disposed() || !this.#ports.terminal.running)
+            return;
+        if (this.#ports.terminal.hasOverlay() || !this.#ports.root.usesDefaultInputSurface()) {
+            this.#startupRouteTimer = setTimeout(() => {
+                this.#startupRouteTimer = undefined;
+                this.presentStartupRoute();
+            }, STARTUP_ROUTE_RETRY_MS);
+            this.#startupRouteTimer.unref?.();
+            return;
+        }
+        this.#startupRoute = undefined;
+        this.openRoute(pending.route, pending.input, pending.onClosed);
+    }
+    /** A replaced session takes its dialog with it; a retained startup route still opens. */
+    onSessionReplaced() {
+        this.#close();
+    }
+    dispose() {
+        if (this.#startupRouteTimer !== undefined)
+            clearTimeout(this.#startupRouteTimer);
+        this.#startupRouteTimer = undefined;
+        this.#handle?.hide();
+    }
+    #close() {
+        this.#handle?.hide();
+        this.#clear();
+    }
+    #clear() {
+        this.#handle = undefined;
+        this.#id = undefined;
+        this.#source = undefined;
+    }
+}

package/dist/app/session-shell/dock-chrome.d.ts

@@ -0,0 +1,34 @@
+import type { ImageAttachmentError, OwnedUiSessionViewModel } from "../../contracts/owned-ui/index.js";
+import type { TranscriptViewportFrame } from "../../ui/components/transcript-viewport.js";
+import { type PiShellReleaseUpdateBanner } from "../../integrations/pi/components/shell-presenters-info.js";
+import type { SessionViewportController } from "./session-viewport-controller.js";
+export interface DockNotice {
+    readonly kind: "status" | "warning" | "error" | "new-session";
+    readonly message: string;
+    readonly errorCode?: ImageAttachmentError["code"];
+}
+export interface DockChromePorts {
+    /** Chrome changed; the root invalidates its chrome components. */
+    readonly invalidateChrome: () => void;
+    readonly requestRender: () => void;
+    readonly viewport: Pick<SessionViewportController, "tailControlHovered" | "setTailControl">;
+}
+/**
+ * The transient chrome around bare A1's dock: the one command notice above the editor, the release
+ * banner above Working with its close control, and the short copy acknowledgement.
+ */
+export declare class DockChrome {
+    #private;
+    constructor(ports: DockChromePorts);
+    get notice(): DockNotice | undefined;
+    setNotice(notice: DockNotice): void;
+    dismissNotice(): void;
+    /** Forgets the notice without a chrome invalidation; the caller invalidates as part of a larger change. */
+    forgetNotice(): void;
+    renderNotice(width: number, outputPad: 0 | 1): readonly string[];
+    showCopyAcknowledgement(message: string): void;
+    clearCopyAcknowledgement(requestRender: boolean): void;
+    renderCopyAcknowledgement(width: number): string | undefined;
+    renderReleaseBanner(diagnostics: OwnedUiSessionViewModel["diagnostics"], width: number): PiShellReleaseUpdateBanner | undefined;
+    locateReleaseClose(frame: TranscriptViewportFrame, banner: PiShellReleaseUpdateBanner | undefined, tailEnd: number, tailLength: number): void;
+}

package/dist/app/session-shell/dock-chrome.js

@@ -0,0 +1,109 @@
+import { renderPiShellCommandMessage, renderPiShellReleaseUpdateBanner, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
+import { PINNED_PI_LAYOUT, piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
+import { piShellTruncateToWidth } from "../../integrations/pi/components/shell-shared-facade.js";
+import { parseReleaseUpdateDiagnostic } from "./transcript-document.js";
+const COPY_ACKNOWLEDGEMENT_DURATION_MS = 1_000;
+/**
+ * The transient chrome around bare A1's dock: the one command notice above the editor, the release
+ * banner above Working with its close control, and the short copy acknowledgement.
+ */
+export class DockChrome {
+    #ports;
+    #notice;
+    // Invariant: bare A1 docks the release notice above the live status; closing it lasts for this session only.
+    #releaseDismissed = false;
+    #releaseCloseTarget;
+    #copyAcknowledgement;
+    #copyAcknowledgementTimer;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    get notice() {
+        return this.#notice;
+    }
+    setNotice(notice) {
+        this.#notice = notice;
+        this.#ports.invalidateChrome();
+    }
+    dismissNotice() {
+        if (this.#notice === undefined)
+            return;
+        this.#notice = undefined;
+        this.#ports.invalidateChrome();
+    }
+    /** Forgets the notice without a chrome invalidation; the caller invalidates as part of a larger change. */
+    forgetNotice() {
+        this.#notice = undefined;
+    }
+    renderNotice(width, outputPad) {
+        const notice = this.#notice;
+        if (notice === undefined)
+            return [];
+        if (notice.kind === "status") {
+            // Compatibility: Pi pads its status text by one cell regardless of the output pad setting.
+            return ["", ...renderPiShellStatusText(notice.message, width, PINNED_PI_LAYOUT.outputPad)];
+        }
+        return renderPiShellCommandMessage({
+            kind: notice.kind === "new-session" ? "accent" : notice.kind,
+            message: notice.message,
+        }, width, outputPad);
+    }
+    showCopyAcknowledgement(message) {
+        this.clearCopyAcknowledgement(false);
+        this.#copyAcknowledgement = message;
+        const timer = setTimeout(() => {
+            if (this.#copyAcknowledgementTimer !== timer)
+                return;
+            this.#copyAcknowledgementTimer = undefined;
+            this.#copyAcknowledgement = undefined;
+            this.#ports.invalidateChrome();
+            this.#ports.requestRender();
+        }, COPY_ACKNOWLEDGEMENT_DURATION_MS);
+        timer.unref?.();
+        this.#copyAcknowledgementTimer = timer;
+        this.#ports.invalidateChrome();
+        this.#ports.requestRender();
+    }
+    clearCopyAcknowledgement(requestRender) {
+        if (this.#copyAcknowledgementTimer !== undefined)
+            clearTimeout(this.#copyAcknowledgementTimer);
+        this.#copyAcknowledgementTimer = undefined;
+        if (this.#copyAcknowledgement === undefined)
+            return;
+        this.#copyAcknowledgement = undefined;
+        this.#ports.invalidateChrome();
+        if (requestRender)
+            this.#ports.requestRender();
+    }
+    renderCopyAcknowledgement(width) {
+        if (this.#copyAcknowledgement === undefined || width <= 0)
+            return undefined;
+        return piTheme().fg("accent", piShellTruncateToWidth(this.#copyAcknowledgement, width));
+    }
+    renderReleaseBanner(diagnostics, width) {
+        if (this.#releaseDismissed)
+            return undefined;
+        const diagnostic = diagnostics.findLast(item => item.code === "release-update");
+        const release = diagnostic === undefined ? null : parseReleaseUpdateDiagnostic(diagnostic.message);
+        if (release === null)
+            return undefined;
+        return renderPiShellReleaseUpdateBanner(release, width, this.#ports.viewport.tailControlHovered(this.#releaseCloseTarget));
+    }
+    locateReleaseClose(frame, banner, tailEnd, tailLength) {
+        // Invariant: the tail is the document suffix, so the control's document row is fixed relative to its
+        // end; alignment gap rows precede it and the viewport scroll decides whether it is on screen.
+        const bannerStart = tailEnd + frame.descriptor.transientAlignmentGapRows - tailLength - frame.scrollTop + 1;
+        const rowStart = banner === undefined ? 0 : Math.max(1, bannerStart + banner.close.rowStart);
+        const rowEnd = banner === undefined ? 0 : Math.min(frame.hits.viewportHeight, bannerStart + banner.close.rowEnd);
+        this.#releaseCloseTarget = banner !== undefined && rowStart <= rowEnd
+            ? { rowStart, rowEnd, columnStart: banner.close.columnStart, columnEnd: banner.close.columnEnd }
+            : undefined;
+        this.#ports.viewport.setTailControl(this.#releaseCloseTarget === undefined ? undefined : {
+            ...this.#releaseCloseTarget,
+            activate: () => {
+                this.#releaseDismissed = true;
+                this.#releaseCloseTarget = undefined;
+            },
+        });
+    }
+}

package/dist/app/session-shell/exit-notice.d.ts

@@ -1,4 +1,4 @@
-import { type SessionResumeCommandMetadata } from "./session-shell.js";
+import { type SessionResumeCommandMetadata } from "./session-lifecycle.js";
 export interface ExitNoticeSource {
     readonly identity: {
         readonly sessionGeneration: number;

package/dist/app/session-shell/exit-notice.js

@@ -6,7 +6,7 @@
  */
 import { renameSync, rmSync, writeFileSync } from "node:fs";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { formatSessionResumeCommand } from "./session-shell.js";
+import { formatSessionResumeCommand } from "./session-lifecycle.js";
 export function uncleanExitNoticeLines(resume) {
     return [
         `${PRODUCT_IDENTITY.displayName} was stopped unexpectedly.`,

package/dist/app/session-shell/extension-surface.d.ts

@@ -0,0 +1,30 @@
+import type { OwnedUiSessionViewModel } from "../../contracts/owned-ui/index.js";
+import type { PiShellComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+export type ExtensionWidgetPlacement = "aboveEditor" | "belowEditor";
+/**
+ * What extensions draw into the shell: a header that replaces the built-in one, a footer, widgets
+ * above and below the editor, footer statuses, and a working message. It owns those components and
+ * disposes each one it replaces; the root decides what to invalidate after a change.
+ */
+export declare class ExtensionSurface {
+    #private;
+    get header(): PiShellComponentPort | null;
+    get footer(): PiShellComponentPort | null;
+    get working(): {
+        readonly message: string | undefined;
+        readonly visible: boolean;
+    };
+    placeWidget(key: string, component: PiShellComponentPort | null, placement: ExtensionWidgetPlacement): void;
+    replaceHeader(component: PiShellComponentPort | null): void;
+    replaceFooter(component: PiShellComponentPort | null): void;
+    setStatus(key: string, text: string | undefined): void;
+    setWorking(message: string | undefined, visible: boolean): void;
+    statuses(): Map<string, string>;
+    /** The view with extension statuses merged over the engine's footer statuses. */
+    withStatuses(view: OwnedUiSessionViewModel): OwnedUiSessionViewModel;
+    renderWidgets(placement: ExtensionWidgetPlacement, width: number): readonly string[];
+    invalidate(): void;
+    /** Disposes and forgets everything an extension set; working visibility is the extension's own choice and stays. */
+    reset(): void;
+    dispose(): void;
+}

package/dist/app/session-shell/extension-surface.js

@@ -0,0 +1,105 @@
+/**
+ * What extensions draw into the shell: a header that replaces the built-in one, a footer, widgets
+ * above and below the editor, footer statuses, and a working message. It owns those components and
+ * disposes each one it replaces; the root decides what to invalidate after a change.
+ */
+export class ExtensionSurface {
+    #header = null;
+    #footer = null;
+    #widgets = new Map();
+    #statuses = new Map();
+    #workingMessage;
+    #workingVisible = true;
+    get header() {
+        return this.#header;
+    }
+    get footer() {
+        return this.#footer;
+    }
+    get working() {
+        return { message: this.#workingMessage, visible: this.#workingVisible };
+    }
+    placeWidget(key, component, placement) {
+        const previous = this.#widgets.get(key)?.component;
+        if (component === null)
+            this.#widgets.delete(key);
+        else
+            this.#widgets.set(key, { component, placement });
+        if (previous !== undefined && previous !== component)
+            previous.dispose?.();
+    }
+    replaceHeader(component) {
+        if (this.#header !== component)
+            this.#header?.dispose?.();
+        this.#header = component;
+    }
+    replaceFooter(component) {
+        if (this.#footer !== component)
+            this.#footer?.dispose?.();
+        this.#footer = component;
+    }
+    setStatus(key, text) {
+        if (text === undefined)
+            this.#statuses.delete(key);
+        else
+            this.#statuses.set(key, text);
+    }
+    setWorking(message, visible) {
+        this.#workingMessage = message;
+        this.#workingVisible = visible;
+    }
+    statuses() {
+        return new Map(this.#statuses);
+    }
+    /** The view with extension statuses merged over the engine's footer statuses. */
+    withStatuses(view) {
+        const footer = view.status.footer;
+        const statuses = new Map(footer?.extensionStatuses ?? []);
+        for (const [key, text] of this.#statuses)
+            statuses.set(key, text);
+        return {
+            ...view,
+            status: {
+                ...view.status,
+                footer: {
+                    ...footer,
+                    branch: footer?.branch ?? null,
+                    sessionName: footer?.sessionName ?? null,
+                    availableProviderCount: footer?.availableProviderCount ?? 1,
+                    extensionStatuses: [...statuses],
+                },
+            },
+        };
+    }
+    renderWidgets(placement, width) {
+        const rows = [...this.#widgets.values()]
+            .filter(widget => widget.placement === placement)
+            .flatMap(widget => widget.component.render(width));
+        return placement === "aboveEditor" ? ["", ...rows] : rows;
+    }
+    invalidate() {
+        this.#header?.invalidate();
+        this.#footer?.invalidate();
+        for (const { component } of this.#widgets.values())
+            component.invalidate();
+    }
+    /** Disposes and forgets everything an extension set; working visibility is the extension's own choice and stays. */
+    reset() {
+        this.#header?.dispose?.();
+        this.#footer?.dispose?.();
+        for (const { component } of this.#widgets.values())
+            component.dispose?.();
+        this.#header = null;
+        this.#footer = null;
+        this.#widgets.clear();
+        this.#statuses.clear();
+        this.#workingMessage = undefined;
+    }
+    dispose() {
+        this.#header?.dispose?.();
+        this.#footer?.dispose?.();
+        for (const { component } of this.#widgets.values())
+            component.dispose?.();
+        this.#widgets.clear();
+    }
+}

package/dist/app/session-shell/input-surface-switch.d.ts

@@ -0,0 +1,36 @@
+import type { PiShellComponentPort, PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PiTuiInputSurfaceKind } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
+import type { SessionViewportController } from "./session-viewport-controller.js";
+export interface InputSurfaceSwitchPorts {
+    /** Whether keystrokes that cannot change the transcript may repaint the dock alone. */
+    readonly dockInputReuse: boolean;
+    readonly viewport: Pick<SessionViewportController, "invalidateInputSurface" | "presentationRevision">;
+    /** The surface changed; listeners outside the root react. */
+    readonly onChanged?: () => void;
+}
+/**
+ * Which component receives the dock's input: the prompt editor, or a selector, dialog, or prompt
+ * that temporarily replaces it. It also records whether the latest keystroke is safe for a
+ * dock-only repaint; that receipt-time evidence never authorizes reuse by itself.
+ */
+export declare class InputSurfaceSwitch {
+    #private;
+    constructor(editor: PiShellEditorPort, ports: InputSurfaceSwitchPorts);
+    get surface(): PiShellComponentPort;
+    get coordination(): PiTuiInputSurfaceKind;
+    get usesEditor(): boolean;
+    get dockInputCandidate(): boolean;
+    get dockInputRevision(): number | undefined;
+    /**
+     * Shows `component` in the dock, or the editor for null. Returns false when the surface is
+     * unchanged, in which case only its coordination kind is updated.
+     */
+    set(component: PiShellComponentPort | null, disposePrevious: boolean, coordination: Exclude<PiTuiInputSurfaceKind, "editor">): boolean;
+    handleInput(data: string): void;
+    /** Reads and clears the dock-only candidate for one composition. */
+    takeDockInputCandidate(): boolean;
+    /** Something outside the dock changed, so the latest keystroke no longer qualifies for reuse. */
+    clearDockInputCandidate(): void;
+    /** Disposes a replacement surface; the editor is disposed by its owner. */
+    dispose(): void;
+}

package/dist/app/session-shell/input-surface-switch.js

@@ -0,0 +1,85 @@
+import { classifyPiTuiInput } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
+/**
+ * Which component receives the dock's input: the prompt editor, or a selector, dialog, or prompt
+ * that temporarily replaces it. It also records whether the latest keystroke is safe for a
+ * dock-only repaint; that receipt-time evidence never authorizes reuse by itself.
+ */
+export class InputSurfaceSwitch {
+    #editor;
+    #ports;
+    #surface;
+    #coordination = "editor";
+    #dockInputCandidate = false;
+    // Invariant: receipt-time eligibility is evidence, never authorization for composition-time reuse.
+    #dockInputRevision;
+    constructor(editor, ports) {
+        this.#editor = editor;
+        this.#ports = ports;
+        this.#surface = editor;
+    }
+    get surface() {
+        return this.#surface;
+    }
+    get coordination() {
+        return this.#coordination;
+    }
+    get usesEditor() {
+        return this.#surface === this.#editor;
+    }
+    get dockInputCandidate() {
+        return this.#dockInputCandidate;
+    }
+    get dockInputRevision() {
+        return this.#dockInputRevision;
+    }
+    /**
+     * Shows `component` in the dock, or the editor for null. Returns false when the surface is
+     * unchanged, in which case only its coordination kind is updated.
+     */
+    set(component, disposePrevious, coordination) {
+        const next = component ?? this.#editor;
+        const nextCoordination = next === this.#editor ? "editor" : coordination;
+        if (next === this.#surface) {
+            this.#coordination = nextCoordination;
+            return false;
+        }
+        this.#dockInputCandidate = false;
+        this.#ports.viewport.invalidateInputSurface();
+        this.#surface.setFocused?.(false);
+        if (disposePrevious && this.#surface !== this.#editor)
+            this.#surface.dispose?.();
+        this.#surface = next;
+        this.#coordination = nextCoordination;
+        this.#ports.onChanged?.();
+        this.#surface.setFocused?.(true);
+        return true;
+    }
+    handleInput(data) {
+        this.#dockInputCandidate = this.#ports.dockInputReuse && classifyPiTuiInput(data, this.#coordination) === "safe";
+        this.#dockInputRevision = this.#dockInputCandidate ? this.#ports.viewport.presentationRevision : undefined;
+        try {
+            this.#surface.handleInput?.(data);
+        }
+        catch (error) {
+            this.#dockInputCandidate = false;
+            throw error;
+        }
+    }
+    /** Reads and clears the dock-only candidate for one composition. */
+    takeDockInputCandidate() {
+        const candidate = this.#dockInputCandidate;
+        this.#dockInputCandidate = false;
+        return candidate;
+    }
+    /** Something outside the dock changed, so the latest keystroke no longer qualifies for reuse. */
+    clearDockInputCandidate() {
+        this.#dockInputCandidate = false;
+        this.#dockInputRevision = undefined;
+    }
+    /** Disposes a replacement surface; the editor is disposed by its owner. */
+    dispose() {
+        this.clearDockInputCandidate();
+        if (this.#surface !== this.#editor)
+            this.#surface.dispose?.();
+    }
+}

package/dist/app/session-shell/login-interaction.d.ts

@@ -0,0 +1,27 @@
+import type { OwnedUiWorkflowInteractionRequest, OwnedUiWorkflowLoginNotification, OwnedUiWorkflowLoginStart } from "../../contracts/owned-ui/index.js";
+import type { ProgramStatusReporter } from "../../integrations/pi/components/upstream/program-status-reporter.js";
+import type { SessionConcern } from "./session-concern.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+import { type OwnedUiPresenterTerminal } from "./shell-host.js";
+export interface LoginInteractionPorts {
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "viewport" | "requestRender">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "setInputSurface">;
+    readonly programStatus: Pick<ProgramStatusReporter, "setBlocked">;
+    /** The blocked-on-authentication state changed; the presenter republishes terminal progress. */
+    readonly syncProgress: () => void;
+}
+/**
+ * The engine's login flow in the dock: one login dialog at a time, the prompts and selections the
+ * engine asks through it, and the terminal's blocked-on-authentication status while it is open.
+ */
+export declare class LoginInteraction implements SessionConcern {
+    #private;
+    constructor(ports: LoginInteractionPorts);
+    start(request: OwnedUiWorkflowLoginStart): void;
+    /** Answers an engine prompt through the open dialog; null when no login is in progress or it is cancelled. */
+    requestInput(request: OwnedUiWorkflowInteractionRequest): Promise<string | null>;
+    notify(event: OwnedUiWorkflowLoginNotification): void;
+    finish(): void;
+    /** A replaced session forgets its dialog; the presenter clears the input surface as part of the same replacement. */
+    onSessionReplaced(): void;
+}