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

package/dist/app/session-shell/prompt-suggestion-controller.js

@@ -1,9 +1,17 @@
 import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../contracts/owned-ui/index.js";
-/** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
+const TRANSIENT_PRESENTATION_REASONS = new Set([
+    "not-ready", "not-focused", "autocomplete", "prompt-mode",
+]);
+const RETRYABLE_OUTCOMES = new Set([
+    "empty", "rejected", "provider-failure", "unavailable", "timeout",
+]);
+/** Prefetches one inert candidate and owns one bounded settlement/retry recovery lifecycle. */
 export class ContextualPromptSuggestionController {
     #state = { status: "idle" };
+    #lifecycle = null;
     #request = null;
     #lastConsidered = "";
+    #retiredIdentity = "";
     #enabled;
     #disposed = false;
     #sessionKey = "";
@@ -27,6 +35,7 @@ export class ContextualPromptSuggestionController {
     }
     skip(identity, reason) {
         this.invalidate();
+        this.#lastConsidered = decisionIdentityKey(identity);
         this.#emit(this.#metadata(identity), "skipped", reason);
     }
     consider(identity, decision) {
@@ -34,51 +43,43 @@ export class ContextualPromptSuggestionController {
         if (key === this.#lastConsidered)
             return;
         this.#lastConsidered = key;
-        this.invalidate();
-        const reason = this.#disposed ? "disposed" : !this.#enabled ? "disabled"
-            : decision === false ? "ineligible" : decision === true ? null : decision;
+        this.#reset(true, true);
+        const reason = this.#decisionReason(decision);
         if (reason !== null) {
             this.#emit(this.#metadata(identity), "skipped", reason);
             return;
         }
-        let reasoning = "unavailable";
-        try {
-            reasoning = this.options.generator.suggestionReasoningPolicy?.() ?? "unavailable";
-        }
-        catch { /* Security: isolate diagnostic metadata failure. */ }
-        const request = {
-            identity,
-            metadata: { ...this.#metadata(identity), request: ++this.#requestSequence, reasoning },
-            abort: new AbortController(), startedAt: this.#now(), terminal: false,
-        };
-        this.#request = request;
-        this.#state = { status: "generating", identity, settled: false };
-        this.#emit(request.metadata, "started");
-        request.timer = setTimeout(() => {
-            if (this.#request !== request || this.#state.status !== "generating")
-                return;
-            this.#finish(request, "timeout");
-            this.#state = { status: "idle" };
-            this.#request = null;
-            request.abort.abort();
-        }, this.#timeoutMs);
-        request.timer.unref?.();
-        try {
-            void this.options.generator.generate({ identity, signal: request.abort.signal })
-                .then(result => this.#receive(request, result), () => this.#failed(request))
-                .finally(() => clearTimeout(request.timer));
-        }
-        catch {
-            this.#failed(request);
-        }
+        this.#retiredIdentity = "";
+        this.#lifecycle = { identity, settled: false, attempts: 0, retryPending: false, presentationDeferred: false };
+        this.#startAttempt("prefetch");
     }
-    settle(identity) {
-        if (this.#disposed || !this.#enabled || this.#state.status === "idle")
+    /** Settles an existing prefetch or starts the first request when that eligible prefetch was missed. */
+    settle(identity, decision = null) {
+        if (this.#disposed || !this.#enabled || identityKey(identity) === this.#retiredIdentity)
             return;
-        if (!samePromptSuggestionIdentity(this.#state.identity, identity)) {
+        const reason = this.#decisionReason(decision);
+        const lifecycle = this.#lifecycle;
+        if (lifecycle !== null && !samePromptSuggestionIdentity(lifecycle.identity, identity)) {
             if (this.#request)
                 this.#finish(this.#request, "stale-result", "stale-identity");
-            this.invalidate();
+            this.#reset(true, true);
+        }
+        if (reason !== null) {
+            if (this.#lifecycle !== null)
+                this.#reset(true, true);
+            else
+                this.#emit(this.#metadata(identity), "skipped", reason);
+            return;
+        }
+        if (this.#lifecycle === null) {
+            this.#retiredIdentity = "";
+            this.#lifecycle = { identity, settled: true, attempts: 0, retryPending: false, presentationDeferred: false };
+            this.#startAttempt("settlement");
+            return;
+        }
+        this.#lifecycle.settled = true;
+        if (this.#lifecycle.retryPending) {
+            this.#startAttempt("retry");
             return;
         }
         if (this.#state.status === "generating")
@@ -86,23 +87,23 @@ export class ContextualPromptSuggestionController {
         else if (this.#state.status === "prepared" && this.#request)
             this.#show(this.#request, this.#state.text);
     }
-    accept() { this.#invalidate(false); }
-    invalidate() { this.#invalidate(true); }
-    /** Retires only a generating request; a prepared or available suggestion survives the draft edit. */
+    accept() { this.#reset(false, true); }
+    invalidate() { this.#reset(true, true); }
+    /** Retires generating or scheduled recovery; a prepared or available suggestion survives a draft edit. */
     abortPending() {
-        if (this.#state.status !== "generating")
-            return;
-        const request = this.#request;
-        this.#request = null;
-        this.#state = { status: "idle" };
-        if (request === null)
+        if (this.#state.status !== "generating" && !(this.#state.status === "idle" && this.#lifecycle?.retryPending))
             return;
-        this.#finish(request, "cancelled");
-        request.abort.abort();
+        this.#reset(false, true);
     }
-    /** Reasserts retained ghost text after an editor mutation makes the prompt eligible again. */
+    /** Reasserts retained ghost text or retries a deferred presentation when the editor is eligible. */
     restoreAvailable() {
-        if (this.#disposed || !this.#enabled || this.#state.status !== "available")
+        if (this.#disposed || !this.#enabled)
+            return;
+        if (this.#state.status === "prepared" && this.#lifecycle?.settled && this.#request) {
+            this.#show(this.#request, this.#state.text);
+            return;
+        }
+        if (this.#state.status !== "available")
             return;
         const reason = this.options.surface.presentationBlockReason?.(this.#state.identity)
             ?? (this.options.surface.canPresent(this.#state.identity) ? null : "presentation-unavailable");
@@ -114,16 +115,64 @@ export class ContextualPromptSuggestionController {
         this.#disposed = true;
         this.invalidate();
         this.#lastConsidered = "";
+        this.#retiredIdentity = "";
         this.#sessionKey = "";
     }
-    #invalidate(clearSurface) {
+    #decisionReason(decision) {
+        return this.#disposed ? "disposed" : !this.#enabled ? "disabled"
+            : decision === false ? "ineligible" : decision === true ? null : decision;
+    }
+    #startAttempt(trigger) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle === null || this.#request !== null || lifecycle.attempts >= 2)
+            return;
+        lifecycle.retryPending = false;
+        lifecycle.presentationDeferred = false;
+        const attempt = ++lifecycle.attempts;
+        let reasoning = "unavailable";
+        try {
+            reasoning = this.options.generator.suggestionReasoningPolicy?.() ?? "unavailable";
+        }
+        catch { /* Security: isolate diagnostic metadata failure. */ }
+        const request = {
+            identity: lifecycle.identity,
+            metadata: { ...this.#metadata(lifecycle.identity), request: ++this.#requestSequence, reasoning, attempt, trigger },
+            abort: new AbortController(), startedAt: this.#now(), terminal: false,
+        };
+        this.#request = request;
+        this.#state = { status: "generating", identity: lifecycle.identity, settled: lifecycle.settled };
+        this.#emit(request.metadata, "started");
+        request.timer = setTimeout(() => {
+            if (this.#request !== request || this.#state.status !== "generating")
+                return;
+            this.#finish(request, "timeout");
+            this.#request = null;
+            this.#state = { status: "idle" };
+            request.abort.abort();
+            this.#completeNoCandidate(request, "timeout");
+        }, this.#timeoutMs);
+        request.timer.unref?.();
+        try {
+            void this.options.generator.generate({ identity: lifecycle.identity, signal: request.abort.signal })
+                .then(result => this.#receive(request, result), () => this.#failed(request))
+                .finally(() => clearTimeout(request.timer));
+        }
+        catch {
+            this.#failed(request);
+        }
+    }
+    #reset(clearSurface, retire) {
         const hadVisibleSuggestion = this.#state.status === "available";
+        const identity = this.#lifecycle?.identity ?? (this.#state.status === "idle" ? null : this.#state.identity);
         const request = this.#request;
         if (request)
             this.#finish(request, "cancelled");
         this.#request = null;
+        this.#lifecycle = null;
         this.#state = { status: "idle" };
         request?.abort.abort();
+        if (retire && identity !== null)
+            this.#retiredIdentity = identityKey(identity);
         if (clearSurface && hadVisibleSuggestion) {
             this.options.surface.clear();
             this.options.surface.requestRender();
@@ -137,6 +186,7 @@ export class ContextualPromptSuggestionController {
         this.#finish(request, "provider-failure");
         this.#request = null;
         this.#state = { status: "idle" };
+        this.#completeNoCandidate(request, "provider-failure");
     }
     #receive(request, result) {
         if (this.#disposed || this.#request !== request || request.terminal || this.#state.status !== "generating") {
@@ -148,41 +198,76 @@ export class ContextualPromptSuggestionController {
         }
         catch {
             this.#finish(request, "rejected");
-            this.invalidate();
+            this.#request = null;
+            this.#state = { status: "idle" };
+            this.#completeNoCandidate(request, "rejected");
             return;
         }
         if (!samePromptSuggestionIdentity(request.identity, result.identity)) {
             this.#finish(request, "stale-result", "stale-identity");
-            this.invalidate();
+            this.#reset(true, true);
             return;
         }
         if (result.outcome !== "candidate") {
             this.#finish(request, result.outcome);
-            this.invalidate();
+            this.#request = null;
+            this.#state = { status: "idle" };
+            if (RETRYABLE_OUTCOMES.has(result.outcome))
+                this.#completeNoCandidate(request, result.outcome);
+            else {
+                this.#retiredIdentity = identityKey(request.identity);
+                this.#lifecycle = null;
+            }
             return;
         }
         const text = normalizePromptSuggestionCandidate(result.text);
         if (text === null) {
             this.#finish(request, "rejected");
-            this.invalidate();
+            this.#request = null;
+            this.#state = { status: "idle" };
+            this.#completeNoCandidate(request, "rejected");
             return;
         }
         clearTimeout(request.timer);
-        if (this.#state.settled)
+        if (this.#lifecycle?.settled)
             this.#show(request, text);
         else
             this.#state = { status: "prepared", identity: request.identity, text };
     }
+    #completeNoCandidate(request, outcome) {
+        const lifecycle = this.#lifecycle;
+        if (lifecycle === null || !samePromptSuggestionIdentity(lifecycle.identity, request.identity))
+            return;
+        if (lifecycle.attempts >= 2 || !RETRYABLE_OUTCOMES.has(outcome)) {
+            this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, "retry-exhausted");
+            this.#retiredIdentity = identityKey(request.identity);
+            this.#lifecycle = null;
+            return;
+        }
+        lifecycle.retryPending = true;
+        if (lifecycle.settled)
+            this.#startAttempt("retry");
+    }
     #show(request, text) {
         const reason = this.options.surface.presentationBlockReason?.(request.identity)
             ?? (this.options.surface.canPresent(request.identity) ? null : "presentation-unavailable");
+        if (reason !== null && TRANSIENT_PRESENTATION_REASONS.has(reason)) {
+            this.#state = { status: "prepared", identity: request.identity, text };
+            if (this.#lifecycle !== null && !this.#lifecycle.presentationDeferred) {
+                this.#lifecycle.presentationDeferred = true;
+                this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, "presentation-deferred", reason);
+            }
+            return;
+        }
         if (reason !== null || !this.options.surface.present(text)) {
             this.#finish(request, "presentation-blocked", reason ?? "presentation-unavailable");
-            this.invalidate();
+            this.#reset(true, true);
             return;
         }
         this.#state = { status: "available", identity: request.identity, text };
         this.#finish(request, "displayed");
+        if (this.#lifecycle !== null)
+            this.#lifecycle.presentationDeferred = false;
         this.options.surface.requestRender();
     }
     #finish(request, event, reason) {
@@ -227,3 +312,8 @@ export function samePromptSuggestionIdentity(left, right) {
 function identityKey(identity) {
     return `${identity.sessionId}\0${identity.sessionGeneration}\0${identity.runSequence}\0${identity.responseSequence}\0${identity.model.providerId}\0${identity.model.modelId}`;
 }
+function decisionIdentityKey(identity) {
+    return identity.model === null
+        ? `${identity.sessionId}\0${identity.sessionGeneration}\0${identity.runSequence}\0${identity.responseSequence}\0\0`
+        : identityKey(identity);
+}

package/dist/app/session-shell/quit-outro.d.ts

@@ -15,6 +15,8 @@ export interface QuitOutroPlayback {
     sleep?(ms: number): Promise<void>;
     /** Plan seed; defaults to a time- and geometry-derived value. */
     readonly seed?: number;
+    /** Active bare-A1 canvas; omitted preserves transparent playback bytes. */
+    readonly canvasBackgroundAnsi?: string;
 }
 export declare const QUIT_OUTRO_MIN_MS = 300;
 export declare const QUIT_OUTRO_MAX_MS = 2000;
@@ -29,7 +31,7 @@ export declare function clampQuitOutroDuration(durationMs: number): number;
  */
 export declare function captureQuitOutroFrame(presented: readonly string[], columns: number, rows: number): QuitOutroFrame | null;
 /** The clear-and-repaint block that seeds the animation surface with the captured frame. */
-export declare function createQuitOutroSurfaceFrame(frame: QuitOutroFrame): string;
+export declare function createQuitOutroSurfaceFrame(frame: QuitOutroFrame, canvasBackgroundAnsi?: string): string;
 /**
  * Plays the effect over the frame. Resolves true when the plan was played to
  * completion or abandoned at its guard, false when there was nothing to play.

package/dist/app/session-shell/quit-outro.js

@@ -6,6 +6,7 @@
  * terminal cannot delay restoration past the configured clamp.
  */
 import { displayWidth, truncateToWidth } from "../../ui/components/index.js";
+import { rebaseTerminalDefaultBackground } from "../../integrations/pi/tui-runtime/index.js";
 import { createQuitOutroPlan } from "./quit-outro-effects.js";
 export const QUIT_OUTRO_MIN_MS = 300;
 export const QUIT_OUTRO_MAX_MS = 2000;
@@ -44,14 +45,25 @@ export function captureQuitOutroFrame(presented, columns, rows) {
     return { lines, columns: width, rows: height, rowWidths };
 }
 /** The clear-and-repaint block that seeds the animation surface with the captured frame. */
-export function createQuitOutroSurfaceFrame(frame) {
-    let output = `${SYNC_BEGIN}${HIDE_CURSOR}${CLEAR_SCREEN}${HOME}${RESET}`;
+export function createQuitOutroSurfaceFrame(frame, canvasBackgroundAnsi) {
+    if (canvasBackgroundAnsi === undefined) {
+        let output = `${SYNC_BEGIN}${HIDE_CURSOR}${CLEAR_SCREEN}${HOME}${RESET}`;
+        for (let row = 0; row < frame.rows; row++) {
+            const line = frame.lines[row] ?? "";
+            if (frame.rowWidths[row] > 0)
+                output += `${cursorAt(row, 0)}${line}${RESET}`;
+        }
+        return `${output}${SYNC_END}`;
+    }
+    let output = `${SYNC_BEGIN}${HIDE_CURSOR}${RESET}${canvasBackgroundAnsi}${CLEAR_SCREEN}${HOME}`;
     for (let row = 0; row < frame.rows; row++) {
         const line = frame.lines[row] ?? "";
-        if (frame.rowWidths[row] > 0)
-            output += `${cursorAt(row, 0)}${line}${RESET}`;
+        if (frame.rowWidths[row] > 0) {
+            output += `${cursorAt(row, 0)}${canvasBackgroundAnsi}`
+                + `${rebaseTerminalDefaultBackground(line, canvasBackgroundAnsi)}${RESET}${canvasBackgroundAnsi}`;
+        }
     }
-    return `${output}${SYNC_END}`;
+    return `${output}${RESET}${SYNC_END}`;
 }
 /**
  * Plays the effect over the frame. Resolves true when the plan was played to
@@ -69,20 +81,23 @@ export async function playQuitOutro(frame, effect, durationMs, playback) {
     let sparkleIndex = 0;
     let clearIndex = 0;
     let ticks = 0;
-    playback.write(createQuitOutroSurfaceFrame(frame));
+    const canvas = playback.canvasBackgroundAnsi;
+    playback.write(createQuitOutroSurfaceFrame(frame, canvas));
     const startedAt = now();
     for (;;) {
         ticks += 1;
         const elapsed = now() - startedAt;
         const progress = Math.min(1, elapsed / duration);
-        let output = `${SYNC_BEGIN}${RESET}`;
+        let output = canvas === undefined ? `${SYNC_BEGIN}${RESET}` : `${SYNC_BEGIN}${RESET}${canvas}`;
         while (sparkleIndex < plan.sparkles.length && plan.sparkles[sparkleIndex].start <= progress) {
             const cell = plan.sparkles[sparkleIndex++];
             output += `${cursorAt(cell.row, cell.col)}${cell.color}${cell.glyph}`;
         }
         while (clearIndex < plan.clears.length && plan.clears[clearIndex].end <= progress) {
             const cell = plan.clears[clearIndex++];
-            output += `${cursorAt(cell.row, cell.col)}${RESET} `;
+            output += canvas === undefined
+                ? `${cursorAt(cell.row, cell.col)}${RESET} `
+                : `${cursorAt(cell.row, cell.col)}${RESET}${canvas} `;
         }
         const finished = clearIndex >= plan.clears.length || progress >= 1
             || elapsed > duration + QUIT_OUTRO_GUARD_MS || ticks >= QUIT_OUTRO_MAX_TICKS;

package/dist/app/session-shell/response-copy-transport.d.ts

@@ -1,3 +1,4 @@
+import { HelperPool } from "./helper-pool.js";
 import type { SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
 import { type CopyResult } from "./response-copy-protocol.js";
 export interface ResponseCopyJob {
@@ -8,7 +9,7 @@ export interface ResponseCopyJob {
 }
 export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "injected") => void;
 export type ResponseCopyExecutor = (snapshot: SelectionCopySnapshot, phase: CopyPhaseObserver) => ResponseCopyJob;
-/** The production executor also owns a spare helper; the owner warms it at start and disposes it at shutdown. */
+/** The production executor also holds a spare helper; the owner warms it at start and disposes it at shutdown unless the pool is shared. */
 export interface OwnedResponseCopyExecutor extends ResponseCopyExecutor {
     warm(): void;
     dispose(): void;
@@ -36,4 +37,8 @@ export declare function createResponseCopyExecutor(options?: {
     readonly helper?: URL;
     /** Idle bound for the spare helper; production keeps the default. */
     readonly spareIdleMs?: number;
+    /** Process-wide spare pool shared across sessions; the executor warms it but never disposes it. */
+    readonly pool?: HelperPool;
 }): OwnedResponseCopyExecutor;
+/** A spare-of-one pool of copy helpers; `createResponseCopyExecutor` takes its child and warms the next one after each copy. */
+export declare function createCopyHelperPool(helper?: URL, idleMs?: number): HelperPool;

package/dist/app/session-shell/response-copy-transport.js

@@ -23,7 +23,8 @@ export function hasAsyncClipboardOutput(platform = process.platform, stdout = pr
 }
 /** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
 export function createResponseCopyExecutor(options = {}) {
-    const pool = new HelperPool({ fork: () => forkCopyHelper(options.helper), stop: stopCopyHelper, ...(options.spareIdleMs === undefined ? {} : { idleMs: options.spareIdleMs }) });
+    const pool = options.pool ?? createCopyHelperPool(options.helper, options.spareIdleMs);
+    const ownsPool = options.pool === undefined;
     const execute = (snapshot, phase) => {
         const controller = new AbortController();
         let active;
@@ -70,10 +71,15 @@ export function createResponseCopyExecutor(options = {}) {
     // Rationale: `Object.assign` would copy the getter's value once; the accessor must read the pool each time.
     return Object.defineProperties(execute, {
         warm: { value: () => pool.warm() },
-        dispose: { value: () => pool.dispose() },
+        dispose: { value: () => { if (ownsPool)
+                pool.dispose(); } },
         warmed: { get: () => pool.warmed },
     });
 }
+/** A spare-of-one pool of copy helpers; `createResponseCopyExecutor` takes its child and warms the next one after each copy. */
+export function createCopyHelperPool(helper, idleMs) {
+    return new HelperPool({ fork: () => forkCopyHelper(helper), stop: stopCopyHelper, ...(idleMs === undefined ? {} : { idleMs }) });
+}
 /** Forks one copy helper: bounded IPC only, no clipboard payload in argv or temp files, no inherited terminal descriptors. */
 function forkCopyHelper(helper) {
     const source = new URL(import.meta.url).pathname.endsWith(".ts");

package/dist/app/session-shell/session-shell-root.d.ts

@@ -1,23 +1,21 @@
 import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
-import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
+import type { OwnedUiBackgroundSettingsPort, OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionBackend, OwnedUiSessionPresenters, OwnedUiSessionViewModel, OwnedUiTranscriptRendererPort, OwnedUiWorkflowMessage, OwnedUiWorkflowResult, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
 import type { PiTuiPointerSurface } from "../../integrations/pi/tui-runtime/contracts.js";
 import type { UiRouteHost, UiRouteInput } from "../../ui/apps/contracts.js";
 import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../ui/components/transcript-viewport.js";
-import type { PiEngineAdapter } from "../../integrations/pi/engine/adapter.js";
-import type { PiWorkflowMessage, PiWorkflowResult } from "../../integrations/pi/engine/workflows.js";
 import type { PiShellLazySelectorLoader } from "../../integrations/pi/components/lazy-selectors.js";
 import { type PiShellHotkeysPresentation } from "../../integrations/pi/components/shell-presenters-info.js";
-import { type PiShellClipboardContent, type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import { type PiShellClipboardContent, type PiShellComponentPort, type PiKeybindingsHost, type PiShellEditorPort, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
 import { type PiTuiInputCoordinationScheduler, type PiTuiInputSurfaceKind } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
 import type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiLayoutNode, PiTuiTerminalPort } from "../../integrations/pi/tui-runtime/contracts.js";
 import { type PreparedPrompt } from "./prompt-chips.js";
 import type { PastePreparationClientOptions } from "./paste-preparation-client.js";
+import type { OwnedUiClipboardServices } from "./clipboard-services.js";
 import { type SessionViewportInputResult } from "./session-viewport-controller.js";
 import type { ResponseCopyExecutor } from "./response-copy-transport.js";
 import type { ResponseCopyEvent } from "./response-copy-protocol.js";
 import type { PasteEvent, PasteSource } from "./paste-protocol.js";
 import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
-export type OwnedUiBackendPort = PiEngineAdapter;
 export type OwnedUiTerminalPort = PiTuiTerminalPort;
 type OwnedUiStartupOptions = PiShellHeaderOptions;
 export interface OwnedUiClipboardPort {
@@ -30,7 +28,7 @@ export interface OwnedUiClipboardPort {
 }
 /** The engine session the shell presents and the composition's decisions about it. */
 export interface OwnedUiShellEngineOptions {
-    readonly backend: OwnedUiBackendPort;
+    readonly backend: OwnedUiSessionBackend;
     readonly cwd: string;
     /**
      * Declared A1-owned routes. A route this host claims resolves to its app;
@@ -52,6 +50,8 @@ export interface OwnedUiShellPresentationOptions {
     readonly startup?: OwnedUiStartupOptions;
     /** Live profile-local settings, supplied only to the bare-A1 composition. */
     readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /** Live fullscreen canvas choice, supplied only to the bare-A1 composition. */
+    readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
     /** Deterministic scheduling seam for presentation-cadence tests. */
     readonly stream?: {
         readonly intervalMs?: number;
@@ -130,9 +130,17 @@ export interface OwnedUiShellSkillsOptions {
     readonly presentation: () => "collapse" | "expand";
     readonly onChange: (listener: () => void) => () => void;
 }
+/** Process-wide services composition creates once and every session shell borrows; absent, a shell keeps private ones. */
+export interface OwnedUiShellSharedServices {
+    readonly clipboard?: OwnedUiClipboardServices;
+    /** Must match the shell's layout: the owned-input profile for the custom viewport, Pi's otherwise. */
+    readonly keybindings?: PiKeybindingsHost;
+}
 /** What composes an owned session shell, grouped by the collaborator that provides each part. */
 export interface OwnedUiSessionShellOptions {
     readonly engine: OwnedUiShellEngineOptions;
+    /** Opens the selectors and resolves the transcript renderers whose inputs are engine objects. */
+    readonly presenters: OwnedUiSessionPresenters;
     readonly presentation?: OwnedUiShellPresentationOptions;
     readonly history?: OwnedUiShellHistoryOptions;
     readonly suggestions?: OwnedUiShellSuggestionOptions;
@@ -141,6 +149,7 @@ export interface OwnedUiSessionShellOptions {
     /** Supplied only to the bare-A1 composition; absent keeps the pinned per-skill command list. */
     readonly skills?: OwnedUiShellSkillsOptions;
     readonly diagnostics?: OwnedUiShellDiagnosticOptions;
+    readonly shared?: OwnedUiShellSharedServices;
 }
 /** Composes backend session state into the owned transcript, viewport, editor, and dock presentation. */
 export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
@@ -172,14 +181,16 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly onEditorChange?: (text: string) => void;
         readonly onPromptSuggestionAccepted?: (text: string) => void;
         readonly onInputSurfaceChanged?: () => void;
+        readonly onPromptSuggestionEligibilityChanged?: () => void;
         readonly onCopyText?: (text: string) => void;
         readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
         readonly captureClipboardPaste?: () => PasteSource;
         readonly pasteDiagnostics?: (event: PasteEvent) => void;
         readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent">;
+        readonly keybindings?: PiKeybindingsHost;
         readonly promptImageLimit?: () => number;
         readonly skillsPresentation?: () => "collapse" | "expand";
-    }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
+    }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: OwnedUiTranscriptRendererPort, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
     setEditorPaddingX(padding: number): void;
     setAutocompleteMaxVisible(maxVisible: number): void;
     setOutputPad(padding: 0 | 1): void;
@@ -245,7 +256,7 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         maxScroll: number;
         cause: "initial" | "steady" | "dock-input" | "follow-shift" | "detached" | "geometry-change" | null;
     };
-    /** Visible non-selectable Steering, alignment, and Working rows, for rendering evidence. */
+    /** Visible non-persistent Steering, alignment, and Working rows, for rendering evidence. */
     viewportTransientTailRowCount(): number;
     hasActiveSelection(): boolean;
     setViewportConfig(config: OwnedUiViewportSettings): void;
@@ -265,8 +276,8 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
     exitTranscript(width: number): string;
     appendWorkflowStatus(message: string): void;
-    appendWorkflowMessage(message: PiWorkflowMessage, errorCode?: ImageAttachmentError["code"]): void;
-    appendWorkflowResult(result: PiWorkflowResult, errorCode?: ImageAttachmentError["code"]): void;
+    appendWorkflowMessage(message: OwnedUiWorkflowMessage, errorCode?: ImageAttachmentError["code"]): void;
+    appendWorkflowResult(result: OwnedUiWorkflowResult, errorCode?: ImageAttachmentError["code"]): void;
     toggleThinkingVisibility(): void;
     get toolsExpanded(): boolean;
     setToolsExpanded(expanded: boolean): void;
@@ -295,5 +306,5 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setFocused(focused: boolean): void;
     dispose(): void;
 }
-export declare function shellResourceEntries(backend: OwnedUiBackendPort): readonly PiShellResourceEntry[];
+export declare function shellResourceEntries(backend: OwnedUiSessionBackend): readonly PiShellResourceEntry[];
 export {};