@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.214

package/dist/integrations/pi/session-ui/session-shell.js

@@ -1,10 +1,14 @@
+import { PRODUCT_TEXT } from "../../../product-identity.js";
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../../../ui/components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../engine/index.js";
 import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, onPiThemeChange, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../components/index.js";
-import { PiTuiRuntimeAdapter, } from "../tui-runtime/index.js";
+import { DamageAwareTerminalAdapter, PiTuiRuntimeAdapter, classifyPiTuiInput, } from "../tui-runtime/index.js";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer, } from "./stream-presentation-coalescer.js";
 import { preloadSystemClipboard, readSystemClipboardContent, writeSystemClipboardText, } from "./system-clipboard.js";
 import { OwnedUiSessionShellRoot, shellResourceEntries, } from "./session-shell-root.js";
 export { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+/** Coordinates backend, owned presentation, and Pi TUI lifecycles for one interactive session. */
 export class OwnedUiSessionShell {
     backend;
     root;
@@ -24,8 +28,17 @@ export class OwnedUiSessionShell {
     #disposed = false;
     #pointerReporting = false;
     #customViewport;
+    #damageTerminal;
+    #streamPresentation;
     #removeViewportPreInput;
     #unsubscribeSettings;
+    #unbindPiSettings;
+    #unbindTerminalSettings;
+    #unbindShutdownSettings;
+    #terminalProgressEnabled = false;
+    #showImages = true;
+    #imageWidthCells = 80;
+    #fullscreenExitOutput = "transcript";
     #compactionQueue = [];
     #lastClearTime = 0;
     #lastEscapeTime = 0;
@@ -43,11 +56,19 @@ export class OwnedUiSessionShell {
             this.#resolveStopped = resolve;
         });
         let runtime;
+        let damageTerminal;
+        let streamPresentation;
         let pendingClipboardWrite = Promise.resolve();
         this.root = new OwnedUiSessionShellRoot(this.backend.view(), options.cwd, {
             getColumns: () => runtime?.viewport().columns ?? options.terminal?.columns ?? 80,
             getRows: () => runtime?.viewport().rows ?? options.terminal?.rows ?? 24,
             requestRender: force => runtime?.requestRender(force),
+            onViewportFrame: frame => damageTerminal?.arm(frame.descriptor, {
+                overlayActive: runtime?.hasOverlay() ?? false,
+                selectionActive: this.root.hasActiveSelection(),
+                replacementSurfaceActive: !this.root.usesDefaultInputSurface(),
+            }),
+            enableDockInputReuse: options.inputPresentation?.viewportReuse !== false,
             onSubmit: text => { void this.submit(text); },
             onInterrupt: () => { void this.interrupt(); },
             onClear: () => { void this.clearOrExit(); },
@@ -73,9 +94,17 @@ export class OwnedUiSessionShell {
                 await pendingClipboardWrite;
                 if (options.clipboard === undefined)
                     return readSystemClipboardContent();
-                const image = await options.clipboard.readImage?.();
-                if (image !== null && image !== undefined)
-                    return { kind: "image", ...image };
+                try {
+                    const image = await options.clipboard.readImage?.();
+                    if (image !== null && image !== undefined) {
+                        const canonical = canonicalizeClipboardImage(image);
+                        if (canonical !== null)
+                            return { kind: "image", ...canonical };
+                    }
+                }
+                catch {
+                    // Compatibility: treat an unavailable or malformed image as text-capable clipboard input.
+                }
                 const text = await options.clipboard.readText();
                 return text === null ? null : { kind: "text", text };
             },
@@ -85,8 +114,10 @@ export class OwnedUiSessionShell {
         }, this.backend.agentDir, {
             getMessageRenderer: customType => this.backend.pinnedMessageRenderer(customType),
             getToolDefinition: toolName => this.backend.pinnedToolDefinition(toolName),
-        }, options.sessionLayout);
-        // Bare A1 owns a bounded viewport and therefore always runs on the alternate
+        }, options.sessionLayout, {
+            resolve: assetId => this.backend.resolveTranscriptImage(assetId),
+        });
+        // Invariant: bare A1 owns a bounded viewport and therefore always runs on the alternate
         // fullscreen surface. The pinned comparison profiles still honor Pi's mode.
         const tuiMode = this.#customViewport
             ? "fullscreen"
@@ -94,15 +125,72 @@ export class OwnedUiSessionShell {
         const runtimeOptions = {
             root: this.root,
             mode: tuiMode,
-            ...(this.#customViewport ? {} : { layoutRoot: this.root.layoutRoot() }),
+            ...(this.#customViewport ? {
+                decorateTerminal: (terminal) => {
+                    damageTerminal = new DamageAwareTerminalAdapter(terminal, {
+                        regionalScroll: process.env.TERM !== "dumb",
+                        onResize: () => streamPresentation?.noteImmediatePresentation(),
+                    });
+                    return damageTerminal;
+                },
+                ...(options.inputPresentation?.coordination === false ? {} : {
+                    inputCoordination: {
+                        classify: (data, focusedOverlay) => classifyPiTuiInput(data, focusedOverlay ?? this.root.inputCoordinationSurface()),
+                        onReceipt: () => streamPresentation?.noteImmediatePresentation(),
+                        ...(options.inputPresentation?.scheduler === undefined
+                            ? {}
+                            : { scheduler: options.inputPresentation.scheduler }),
+                    },
+                }),
+            } : { layoutRoot: this.root.layoutRoot() }),
+            ...(options.inputPresentation?.onEvent === undefined ? {} : {
+                inputDiagnostics: {
+                    onEvent: options.inputPresentation.onEvent,
+                    ...(options.inputPresentation.now === undefined ? {} : { now: options.inputPresentation.now }),
+                },
+            }),
             ...(options.terminal === undefined ? {} : { terminal: options.terminal }),
             hardwareCursor: this.backend.view().terminal.hardwareCursor,
         };
         runtime = new PiTuiRuntimeAdapter(runtimeOptions);
         this.runtime = runtime;
+        this.#damageTerminal = damageTerminal ?? null;
+        const presentationInterval = options.streamPresentation?.intervalMs ?? STREAM_PRESENTATION_INTERVAL_MS;
+        streamPresentation = options.streamPresentation?.scheduler === undefined
+            ? new StreamPresentationCoalescer(() => this.runtime.requestRender(), presentationInterval)
+            : new StreamPresentationCoalescer(() => this.runtime.requestRender(), presentationInterval, options.streamPresentation.scheduler);
+        this.#streamPresentation = streamPresentation;
+        const initialPiSettings = this.backend.pinnedSettingsSnapshot();
+        this.runtime.setHardwareCursor(initialPiSettings.showHardwareCursor);
+        this.runtime.setClearOnShrink(initialPiSettings.clearOnShrink);
+        this.#terminalProgressEnabled = initialPiSettings.showTerminalProgress;
+        this.#fullscreenExitOutput = initialPiSettings.fullscreenExitOutput;
+        this.#unbindShutdownSettings = this.backend.bindSettingsOwner("shutdown", {
+            fullscreenExitOutput: { apply() { } },
+        });
+        this.#unbindTerminalSettings = this.backend.bindSettingsOwner("terminal", {
+            showHardwareCursor: { apply: value => {
+                    if (typeof value !== "boolean")
+                        throw new TypeError("Hardware cursor setting is invalid");
+                    this.runtime.setHardwareCursor(value);
+                } },
+            clearOnShrink: { apply: value => {
+                    if (typeof value !== "boolean")
+                        throw new TypeError("Clear-on-shrink setting is invalid");
+                    this.runtime.setClearOnShrink(value);
+                } },
+            showTerminalProgress: { apply: value => {
+                    if (typeof value !== "boolean")
+                        throw new TypeError("Terminal progress setting is invalid");
+                    this.#terminalProgressEnabled = value;
+                    this.#syncTerminalProgress(this.view());
+                } },
+        });
         this.#removeViewportPreInput = this.#customViewport
             ? this.runtime.addPreInputListener(data => {
-                // An overlay or editor-replacement screen owns its entire pointer
+                if (options.inputPresentation?.coordination === false)
+                    this.#streamPresentation.noteImmediatePresentation();
+                // Invariant: an overlay or editor-replacement screen owns its entire pointer
                 // surface. Letting the transcript pre-router inspect those reports
                 // steals settings value menus and numeric +/- controls before the
                 // settings app can receive them.
@@ -129,6 +217,53 @@ export class OwnedUiSessionShell {
         this.#unsubscribeSettings = this.#customViewport && options.viewportSettings
             ? options.viewportSettings.onChange(settings => this.root.setViewportConfig(settings))
             : () => { };
+        this.root.setEditorPaddingX(initialPiSettings.editorPaddingX);
+        this.root.setAutocompleteMaxVisible(initialPiSettings.autocompleteMaxVisible);
+        this.root.setOutputPad(initialPiSettings.outputPad);
+        this.root.setHideThinkingBlock(initialPiSettings.hideThinkingBlock);
+        this.root.setMermaidRenderingMode(initialPiSettings.mermaidRenderingMode);
+        this.#showImages = initialPiSettings.showImages;
+        this.#imageWidthCells = initialPiSettings.imageWidthCells;
+        this.root.setImagePresentation(this.#showImages, this.#imageWidthCells);
+        this.#unbindPiSettings = this.backend.bindSettingsOwner("shell", {
+            editorPaddingX: { apply: value => {
+                    if (typeof value !== "number")
+                        throw new TypeError("Editor padding is invalid");
+                    this.root.setEditorPaddingX(value);
+                } },
+            autocompleteMaxVisible: { apply: value => {
+                    if (typeof value !== "number")
+                        throw new TypeError("Autocomplete maximum is invalid");
+                    this.root.setAutocompleteMaxVisible(value);
+                } },
+            outputPad: { apply: value => {
+                    if (value !== 0 && value !== 1)
+                        throw new TypeError("Output padding is invalid");
+                    this.root.setOutputPad(value);
+                } },
+            hideThinkingBlock: { apply: value => {
+                    if (typeof value !== "boolean")
+                        throw new TypeError("Thinking-block visibility is invalid");
+                    this.root.setHideThinkingBlock(value);
+                } },
+            mermaidRenderingMode: { apply: value => {
+                    if (value !== "off" && value !== "final" && value !== "streaming")
+                        throw new TypeError("Mermaid mode is invalid");
+                    this.root.setMermaidRenderingMode(value);
+                } },
+            showImages: { apply: value => {
+                    if (typeof value !== "boolean")
+                        throw new TypeError("Image visibility is invalid");
+                    this.#showImages = value;
+                    this.root.setImagePresentation(this.#showImages, this.#imageWidthCells);
+                } },
+            imageWidthCells: { apply: value => {
+                    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+                        throw new TypeError("Image width is invalid");
+                    this.#imageWidthCells = value;
+                    this.root.setImagePresentation(this.#showImages, this.#imageWidthCells);
+                } },
+        });
         this.#extensionBridge = createPiExtensionUiBridge({
             runtime: {
                 getColumns: () => this.runtime.viewport().columns,
@@ -136,7 +271,7 @@ export class OwnedUiSessionShell {
                 requestRender: () => this.runtime.requestRender(),
             },
             agentDir: this.backend.agentDir,
-            setInputSurface: component => this.root.setInputSurface(component),
+            setInputSurface: component => this.root.setInputSurface(component, true, "opaque"),
             showOverlay: (component, overlayOptions) => this.runtime.showOverlay(component, overlayOptions),
             listenInput: handler => this.runtime.addInputListener(handler),
             replaceWidget: (key, component, placement) => this.root.setExtensionWidget(key, component, placement),
@@ -150,7 +285,7 @@ export class OwnedUiSessionShell {
             setEditorText: text => this.root.editor.setText(text),
             pasteToEditor: text => this.root.editor.insertText(text),
             addAutocompleteProvider: factory => this.root.editor.addAutocompleteProvider(factory),
-            setCustomEditor: component => this.root.setInputSurface(component),
+            setCustomEditor: component => this.root.setInputSurface(component, true, "opaque"),
             getFooterData: () => this.root.extensionFooterData(),
             getToolsExpanded: () => this.root.toolsExpanded,
             setToolsExpanded: expanded => this.root.setToolsExpanded(expanded),
@@ -163,7 +298,7 @@ export class OwnedUiSessionShell {
         });
         this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
         this.#unsubscribe = this.backend.onEvent(event => {
-            // A streamed chunk names one block, and touching only that block is what keeps the
+            // Performance: a streamed chunk names one block, and touching only that block is what keeps the
             // cost of a chunk the same in a long session as in a new one. Everything else
             // resynchronizes the view, which is cheap next to re-reading the transcript.
             if (event.type === "agent-run-started")
@@ -174,6 +309,7 @@ export class OwnedUiSessionShell {
             const view = event.type === "transcript-block" && this.#sessionGeneration === this.backend.sessionGeneration
                 ? this.#syncBlock(event.block)
                 : semanticOnly ? this.view() : this.#syncView();
+            this.#syncTerminalProgress(view);
             if (view.lifecycle === "ready" && this.#compactionQueue.length > 0)
                 void this.#flushCompactionQueue();
             if (event.type === "session-lifecycle" && event.lifecycle === "stopped")
@@ -185,11 +321,15 @@ export class OwnedUiSessionShell {
     view() {
         return this.backend.view();
     }
+    damagePresentationDecision() {
+        return this.#damageTerminal?.lastDecision ?? null;
+    }
     start() {
         if (this.#started)
             return;
         this.#started = true;
         this.runtime.start();
+        this.#syncTerminalProgress(this.view());
         if (this.#customViewport)
             this.#setPointerReporting(true);
         void this.backend.bindExtensionUi(this.#extensionBridge.context, () => { void this.shutdown(); });
@@ -238,7 +378,11 @@ export class OwnedUiSessionShell {
         }
         if (this.view().status.workingMessage?.startsWith("Compacting") === true) {
             this.root.editor.addToHistory(displayInput);
-            this.#compactionQueue.push({ text: input, type: "steer" });
+            this.#compactionQueue.push({
+                text: input,
+                type: "steer",
+                ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+            });
             this.root.appendWorkflowResult({ command: "compact", outcome: "completed", message: `Queued during compaction: ${input}` });
             this.runtime.requestRender();
             return { outcome: "completed", diagnostic: null };
@@ -269,7 +413,7 @@ export class OwnedUiSessionShell {
             this.root.editor.setText("");
             return { outcome: "completed", diagnostic: null };
         }
-        // Match Pi: with an empty editor, two escapes inside 500 ms open the
+        // Compatibility: match Pi: with an empty editor, two escapes inside 500 ms open the
         // configured session navigator. The first escape intentionally does not
         // interrupt or mutate the prompt.
         const action = this.backend.pinnedSettingsSnapshot().doubleEscapeAction;
@@ -336,14 +480,20 @@ export class OwnedUiSessionShell {
         return workflowAdapterResult(result);
     }
     async queueFollowUp() {
-        const text = this.root.editor.getText().trim();
-        if (!text)
+        const displayInput = this.root.editor.getText().trim();
+        if (!displayInput)
             return rejected("nothing to queue");
-        this.root.editor.addToHistory(text);
+        const prepared = this.root.preparePromptSubmission(displayInput);
+        const text = prepared.text.trim();
+        this.root.editor.addToHistory(displayInput);
         this.root.editor.setText("");
         this.root.resumeViewportFollowing();
         if (this.view().status.workingMessage?.startsWith("Compacting") === true) {
-            this.#compactionQueue.push({ text, type: "follow-up" });
+            this.#compactionQueue.push({
+                text,
+                type: "follow-up",
+                ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+            });
             return { outcome: "completed", diagnostic: null };
         }
         return this.#execute({
@@ -351,6 +501,7 @@ export class OwnedUiSessionShell {
             correlationId: this.#correlation("follow-up"),
             sessionId: this.backend.sessionId,
             text,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
         });
     }
     restoreQueuedInput() {
@@ -381,7 +532,12 @@ export class OwnedUiSessionShell {
                 onCancel?.();
             },
         });
-        const handle = this.runtime.showOverlay(component, { width: "70%", maxHeight: "80%", anchor: "center" });
+        const handle = this.runtime.showOverlay(component, {
+            width: "70%",
+            maxHeight: "80%",
+            anchor: "center",
+            inputCoordination: "owned",
+        });
         this.#dialogHandle = handle;
         return handle;
     }
@@ -581,7 +737,7 @@ export class OwnedUiSessionShell {
                     return;
                 }
                 if (callback === "onTuiModeChange") {
-                    // The custom bare-A1 surface is permanently fullscreen; this callback
+                    // Invariant: the custom bare-A1 surface is permanently fullscreen; this callback
                     // remains available only to pinned comparison profiles.
                     if (this.#customViewport)
                         return;
@@ -597,12 +753,13 @@ export class OwnedUiSessionShell {
                         this.#setPointerReporting(true);
                     }
                 }
-                const result = this.backend.applyPinnedSettingValue(callback, value);
-                if (result.outcome === "failed")
-                    this.root.appendWorkflowResult(result);
-                else if (callback === "onTuiModeChange")
-                    this.root.appendWorkflowStatus(`TUI mode: ${value}`);
-                this.runtime.requestRender();
+                void this.backend.applyPinnedSettingValue(callback, value).then(result => {
+                    if (result.outcome === "failed")
+                        this.root.appendWorkflowResult(result);
+                    else if (callback === "onTuiModeChange")
+                        this.root.appendWorkflowStatus(`TUI mode: ${value}`);
+                    this.runtime.requestRender();
+                });
             },
             onCancel: close,
         });
@@ -801,12 +958,7 @@ export class OwnedUiSessionShell {
             this.root.appendDaxnuts();
         }
     }
-    /**
-     * Turns terminal pointer reporting on for a screen that reads the pointer, and off for
-     * every path that ends it. While it is on the terminal hands A1 the wheel and the
-     * button instead of scrolling and selecting itself, so leaving it on outlives the
-     * screen that wanted it and takes the terminal's own scrolling and selection with it.
-     */
+    // Invariant: pointer reporting is disabled on every path that ends the owning screen.
     #setPointerReporting(enabled, forceOff = false) {
         const effective = forceOff ? false : this.#customViewport || enabled;
         if (this.#pointerReporting === effective)
@@ -823,32 +975,62 @@ export class OwnedUiSessionShell {
         this.root.clearViewportPointerState();
         this.#setPointerReporting(false, true);
         this.#removeViewportPreInput();
+        this.#streamPresentation.dispose();
         this.#unsubscribeSettings();
+        const exitMode = this.backend.disposed
+            ? this.#fullscreenExitOutput
+            : this.backend.pinnedSettingsSnapshot().fullscreenExitOutput;
+        const exitTranscript = this.root.exitTranscript(this.runtime.viewport().columns);
+        const resume = this.backend.currentSessionResumeMetadata();
+        const resumeHint = resume === null
+            ? ""
+            : `${dim("To resume this session:")} ${formatSessionResumeCommand(resume)}`;
+        const fullscreenExitText = this.runtime.mode !== "fullscreen"
+            ? ""
+            : exitMode === "resume-hint"
+                ? resumeHint
+                : [exitTranscript, resumeHint].filter(Boolean).join("\n\n");
+        this.#unbindPiSettings();
+        this.#unbindTerminalSettings();
+        this.#unbindShutdownSettings();
         this.#unsubscribe();
         this.#dialogHandle?.hide();
         await this.backend.unbindExtensionUi();
         this.#extensionBridge.dispose();
         await this.runtime.dispose();
+        if (fullscreenExitText.length > 0)
+            this.runtime.writeAfterStop(`${fullscreenExitText}\n`);
     }
-    /**
-     * Applies one transcript block without re-reading the session. The listeners still hear
-     * the view they would have heard, so nothing downstream can tell the difference.
-     */
+    // Invariant: incremental block updates notify listeners with the same complete view contract.
     #syncBlock(block) {
         this.root.applyTranscriptBlock(block);
-        this.runtime.requestRender();
+        if (this.#customViewport && block.status === "live" && isCoalescedStreamBlock(block.kind)) {
+            this.#streamPresentation.request();
+        }
+        else if (this.#streamPresentation.pending) {
+            this.#streamPresentation.flush();
+        }
+        else {
+            this.#streamPresentation.presentImmediate();
+        }
         const view = this.view();
         for (const listener of this.#listeners)
             listener(view);
         return view;
     }
+    #syncTerminalProgress(view) {
+        if (!this.runtime.active)
+            return;
+        this.runtime.setTerminalProgress(this.#terminalProgressEnabled && view.lifecycle === "busy");
+    }
     #syncView() {
+        this.#streamPresentation.noteImmediatePresentation();
         const view = this.view();
         if (this.backend.sessionGeneration !== this.#sessionGeneration) {
             this.#sessionGeneration = this.backend.sessionGeneration;
             this.#activeLoginDialog = undefined;
             this.#extensionBridge.reset();
-            // A replaced session takes its transient viewport and owned-route state with it.
+            // Invariant: a replaced session takes its transient viewport and owned-route state with it.
             this.root.resetViewport();
             this.#dialogHandle?.hide();
             this.#dialogHandle = undefined;
@@ -874,10 +1056,10 @@ export class OwnedUiSessionShell {
             return { outcome: "failed", diagnostic: "runtime is not active" };
         this.#dialogHandle?.hide();
         this.#dialogSource = "route";
-        // Any-event reporting: hover and drag are what the screen is driven by, and
+        // Protocol: any-event reporting: hover and drag are what the screen is driven by, and
         // it also stops the terminal treating a drag as a text selection.
         this.#setPointerReporting(true);
-        // The interrupt chord is global, so it is watched on raw input rather than
+        // Protocol: the interrupt chord is global, so it is watched on raw input rather than
         // through the overlay: the pinned shell handles that key before an overlay
         // ever sees it, which is why an owned screen must not rely on being asked.
         let armedAt = 0;
@@ -893,7 +1075,7 @@ export class OwnedUiSessionShell {
             }
             armedAt = now;
             this.runtime.requestRender();
-            // The presented screen owns the chord, so the pinned shell never sees a
+            // Invariant: the presented screen owns the chord, so the pinned shell never sees a
             // stray interrupt while it is up.
             return { consume: true };
         });
@@ -907,7 +1089,7 @@ export class OwnedUiSessionShell {
             this.#dialogId = undefined;
             this.#dialogSource = undefined;
         };
-        // Fullscreen Pi owns a fallback text-selection layer before focused overlay
+        // Compatibility: fullscreen Pi owns a fallback text-selection layer before focused overlay
         // components see pointer input. Route every mouse report to the owned screen
         // at the pre-input boundary so dropdowns, value hover, and numeric +/- work,
         // and consume even unhandled reports so settings content is never selected.
@@ -945,7 +1127,12 @@ export class OwnedUiSessionShell {
             closeSurface();
             void this.shutdown();
         });
-        this.#dialogHandle = this.runtime.showOverlay(component, { width: "100%", maxHeight: "100%", anchor: "top-left" });
+        this.#dialogHandle = this.runtime.showOverlay(component, {
+            width: "100%",
+            maxHeight: "100%",
+            anchor: "top-left",
+            inputCoordination: "owned",
+        });
         this.#dialogId = surface.id;
         return { outcome: "completed", diagnostic: null };
     }
@@ -953,7 +1140,7 @@ export class OwnedUiSessionShell {
         if (!this.runtime.active)
             return;
         if (dialog === null) {
-            // Locally owned routes (notably /settings) are independent of backend
+            // Invariant: locally owned routes (notably /settings) are independent of backend
             // lifecycle/status events and remain open while an agent is working.
             if (this.#dialogSource !== "backend")
                 return;
@@ -981,7 +1168,12 @@ export class OwnedUiSessionShell {
                 this.#dialogSource = undefined;
             },
         });
-        this.#dialogHandle = this.runtime.showOverlay(component, { width: "70%", maxHeight: "80%", anchor: "center" });
+        this.#dialogHandle = this.runtime.showOverlay(component, {
+            width: "70%",
+            maxHeight: "80%",
+            anchor: "center",
+            inputCoordination: "owned",
+        });
         this.#dialogId = dialog.id;
     }
     async #slashCommand(text) {
@@ -993,7 +1185,7 @@ export class OwnedUiSessionShell {
             return this.#openOwnedRoute(name);
         if (isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
-        // Unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
+        // Compatibility: unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
         this.root.editor.addToHistory(text);
         this.root.resumeViewportFollowing();
         return this.#execute({
@@ -1117,6 +1309,7 @@ export class OwnedUiSessionShell {
                 correlationId: this.#correlation(`compaction-${item.type}`),
                 sessionId: this.backend.sessionId,
                 text: item.text,
+                ...(item.images === undefined ? {} : { images: item.images }),
             });
         }
     }
@@ -1131,6 +1324,24 @@ export class OwnedUiSessionShell {
         return `pi-shell-${prefix}-${this.#sequence}`;
     }
 }
+function isCoalescedStreamBlock(kind) {
+    return kind === "assistant" || kind === "thinking" || kind === "tool-call" || kind === "tool-result";
+}
+export function formatSessionResumeCommand(metadata) {
+    const args = [PRODUCT_TEXT.commandName];
+    if (!metadata.usesDefaultSessionDir)
+        args.push("--session-dir", quoteCommandArgument(metadata.sessionDir));
+    args.push("--session", metadata.sessionId);
+    return args.join(" ");
+}
+export function quoteCommandArgument(value) {
+    if (value.length > 0 && !/[^a-zA-Z0-9_\-./~:@]/.test(value))
+        return value;
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function dim(value) {
+    return `\u001b[2m${value}\u001b[22m`;
+}
 function modelReference(model) {
     if (typeof model !== "object" || model === null)
         return "";

package/dist/integrations/pi/session-ui/session-viewport-controller.d.ts

@@ -24,11 +24,16 @@ export declare class SessionViewportController {
     get config(): OwnedUiViewportSettings;
     get editorPointerSelecting(): boolean;
     get transcriptPointerSelecting(): boolean;
+    get hasSelection(): boolean;
+    get selectionRevision(): number;
+    get presentationRevision(): number;
+    get frame(): TranscriptViewportFrame | null;
     setEditorPointerFrame(frame: {
         readonly rowStart: number;
         readonly rowEnd: number;
     } | undefined): void;
     compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
     /** Returns true when document wrapping may have changed. */
     setConfig(config: OwnedUiViewportSettings): boolean;
     resumeFollowing(): void;