@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

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

@@ -0,0 +1,278 @@
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../contracts/owned-ui/index.js";
+import type { PiTuiPointerSurface } from "../../integrations/pi/tui-runtime/contracts.js";
+import type { UiRouteHost } 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 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 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 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 {
+    readText(signal?: AbortSignal): Promise<string | null>;
+    readImage?(signal?: AbortSignal): Promise<{
+        readonly data: string;
+        readonly mimeType: string;
+    } | null>;
+    writeText?(text: string, signal?: AbortSignal): Promise<void>;
+}
+/** The engine session the shell presents and the composition's decisions about it. */
+export interface OwnedUiShellEngineOptions {
+    readonly backend: OwnedUiBackendPort;
+    readonly cwd: string;
+    /**
+     * Declared A1-owned routes. A route this host claims resolves to its app;
+     * every other route continues to the pinned workflow table unchanged.
+     */
+    readonly routeHost?: UiRouteHost;
+    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
+    readonly sessionLayout?: "pinned" | "custom-viewport";
+}
+/** Terminal, startup, viewport, and presentation-cadence seams; production leaves most at their defaults. */
+export interface OwnedUiShellPresentationOptions {
+    readonly terminal?: OwnedUiTerminalPort;
+    readonly startup?: OwnedUiStartupOptions;
+    /** Live profile-local settings, supplied only to the bare-A1 composition. */
+    readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /** Deterministic scheduling seam for presentation-cadence tests. */
+    readonly stream?: {
+        readonly intervalMs?: number;
+        readonly scheduler?: StreamPresentationScheduler;
+    };
+    /**
+     * Minimum time the reload box stays visible so a fast reload still reads as one.
+     * Production uses the default hold; tests inject `now`/`sleep` for determinism.
+     */
+    readonly reload?: {
+        readonly minVisibleMs?: number;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+    };
+    /**
+     * Quit outro settings and seams, supplied only to the bare-A1 composition.
+     * `interactive` states whether the terminal can show the animation; production
+     * passes stdout's TTY state, tests opt in explicitly.
+     */
+    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
+        readonly interactive: boolean;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+        readonly seed?: number;
+    };
+    readonly input?: {
+        readonly scheduler?: PiTuiInputCoordinationScheduler;
+        readonly onEvent?: (event: PiTuiInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+        /** Evidence-only baseline seam; production leaves coordination enabled. */
+        readonly coordination?: boolean;
+        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
+        readonly viewportReuse?: boolean;
+    };
+}
+/** Persistent prompt history: its store, its bound, the editor that recalls it, and the image sidecar. */
+export interface OwnedUiShellHistoryOptions {
+    readonly store: import("../../contracts/owned-ui/index.js").PromptHistoryPort;
+    readonly limit: number;
+    readonly editor: import("../../integrations/pi/components/index.js").HistoryEditorConstructor;
+    /** Optional per-profile filesystem sidecar for image chip payloads. When present, submit
+     * writes each referenced attachment and recall reads them back to rehydrate live chips.
+     * When absent, image chips silently strip on recall, matching the missing-sidecar path. */
+    readonly imageSidecar?: import("../../contracts/owned-ui/index.js").PromptHistoryImageSidecarPort;
+}
+/** Contextual prompt suggestions: the generator, the enablement setting, and an optional evidence seam. */
+export interface OwnedUiShellSuggestionOptions {
+    readonly diagnostics?: SuggestionDiagnosticObserver;
+    readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+    readonly enabled: () => boolean;
+    readonly onChange: (listener: (enabled: boolean) => void) => () => void;
+}
+/** Clipboard seams and payload-free diagnostics; comparison profiles ignore the diagnostics. */
+export interface OwnedUiShellDiagnosticOptions {
+    /** Optional platform seam; production uses A1's system clipboard adapter. */
+    readonly clipboard?: OwnedUiClipboardPort;
+    /** Owned response-copy transport and payload-free diagnostic seams. */
+    readonly responseCopy?: {
+        readonly execute?: ResponseCopyExecutor;
+        readonly onEvent?: (event: ResponseCopyEvent) => void;
+    };
+    /** Bounded, payload-free clipboard acquisition/preparation observations. */
+    readonly paste?: (event: PasteEvent) => void;
+    /** Test seams for isolated paste preparation: an in-process starter, or the forked helper's entry. */
+    readonly pastePreparation?: Omit<PastePreparationClientOptions, "onEvent" | "spareIdleMs">;
+}
+/** The skills presentation choice: collapse the per-skill commands into one skills command or expand them. */
+export interface OwnedUiShellSkillsOptions {
+    readonly presentation: () => "collapse" | "expand";
+    readonly onChange: (listener: () => void) => () => void;
+}
+/** What composes an owned session shell, grouped by the collaborator that provides each part. */
+export interface OwnedUiSessionShellOptions {
+    readonly engine: OwnedUiShellEngineOptions;
+    readonly presentation?: OwnedUiShellPresentationOptions;
+    readonly history?: OwnedUiShellHistoryOptions;
+    readonly suggestions?: OwnedUiShellSuggestionOptions;
+    /** Supplied only to the bare-A1 composition; absent keeps the pinned per-skill command list. */
+    readonly skills?: OwnedUiShellSkillsOptions;
+    readonly diagnostics?: OwnedUiShellDiagnosticOptions;
+}
+/** Composes backend session state into the owned transcript, viewport, editor, and dock presentation. */
+export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
+    #private;
+    readonly editor: PiShellEditorPort;
+    readonly header: PiShellHeaderPort;
+    readonly resources: PiShellLoadedResourcesPort;
+    constructor(view: OwnedUiSessionViewModel, cwd: string, handlers: {
+        readonly getColumns: () => number;
+        readonly getRows: () => number;
+        readonly requestRender: (force?: boolean) => void;
+        readonly onViewportFrame?: (frame: TranscriptViewportFrame) => void;
+        readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
+        readonly enableDockInputReuse?: boolean;
+        readonly persistentHistory?: boolean;
+        readonly historyEditor?: import("../../integrations/pi/components/index.js").HistoryEditorConstructor;
+        readonly onSubmit: (text: string) => void;
+        readonly onPasteRejected?: (error: unknown) => void;
+        readonly onInterrupt: () => void;
+        readonly onClear?: () => void;
+        readonly onExit: () => void;
+        readonly onModelSelect: () => void;
+        readonly onModelCycle?: (direction: "forward" | "backward") => void;
+        readonly onThinkingCycle: () => void;
+        readonly onThinkingToggle?: () => void;
+        readonly onMessageCopy?: () => void;
+        readonly onFollowUp?: () => void;
+        readonly onDequeue?: () => void;
+        readonly onEditorChange?: (text: string) => void;
+        readonly onPromptSuggestionAccepted?: (text: string) => void;
+        readonly onInputSurfaceChanged?: () => 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 skillsPresentation?: () => "collapse" | "expand";
+    }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
+    setEditorPaddingX(padding: number): void;
+    setAutocompleteMaxVisible(maxVisible: number): void;
+    setOutputPad(padding: 0 | 1): void;
+    setHideThinkingBlock(hidden: boolean): void;
+    setMermaidRenderingMode(mode: "off" | "final" | "streaming"): void;
+    setImagePresentation(showImages: boolean, imageWidthCells: number): void;
+    prepareHistoryText(text: string): string;
+    rehydrateHistoryText(text: string, resolveImage: (id: string) => import("../../contracts/owned-ui/index.js").PromptHistoryImageSidecarAttachment | null): string;
+    imageChipAttachmentsFromEditor(text: string): {
+        readonly id: string;
+        readonly tag: string;
+        readonly image: {
+            readonly type: "image";
+            readonly data: string;
+            readonly mimeType: string;
+        };
+    }[];
+    preparePromptSubmission(text: string): PreparedPrompt;
+    hasPendingPastes(text: string): boolean;
+    waitForPromptPastes(text: string, signal: AbortSignal): Promise<PreparedPrompt>;
+    resetPendingPastes(): void;
+    /** Forks the spare paste helper so the first paste of the session takes a live child. */
+    warmPastePreparation(): void;
+    disposePendingPastes(): Promise<void>;
+    promptSuggestionPrepareBlockReason(): SuggestionDecision;
+    canPreparePromptSuggestion(): boolean;
+    promptSuggestionPresentationBlockReason(): SuggestionDecision;
+    canPresentPromptSuggestion(): boolean;
+    setPromptSuggestion(text: string | null): void;
+    update(view: OwnedUiSessionViewModel): void;
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    applyTranscriptBlock(block: OwnedUiSessionViewModel["transcript"][number]): void;
+    render(width: number): readonly string[];
+    viewportFrameDescriptor(): TranscriptViewportFrameDescriptor | null;
+    /** Read-only, payload-free evidence; observing a pending frame must never render or repair it. */
+    viewportPresentationEvidence(): {
+        candidate: boolean;
+        candidateRevision: number | null;
+        currentRevision: number;
+        composedRevision: number | null;
+        currentPointer: {
+            readonly column: number;
+            readonly row: number;
+        } | null;
+        composedPointer: {
+            readonly column: number;
+            readonly row: number;
+        } | null;
+        frameId: number | null;
+        bottom: {
+            readonly row: number;
+            readonly columnStart: number;
+            readonly columnEnd: number;
+        } | null;
+        followingEnd: boolean;
+        scrollTop: number;
+        maxScroll: number;
+        cause: "initial" | "steady" | "dock-input" | "follow-shift" | "detached" | "geometry-change" | null;
+    };
+    /** Visible non-selectable Steering, alignment, and Working rows, for rendering evidence. */
+    viewportTransientTailRowCount(): number;
+    hasActiveSelection(): boolean;
+    setViewportConfig(config: OwnedUiViewportSettings): void;
+    setFullscreenCopyOnSelect(enabled: boolean): void;
+    showCopyAcknowledgement(message: string): void;
+    resumeViewportFollowing(): void;
+    noteCompletedAssistantMessage(): void;
+    /** A new session binding owns new mounts even when it reuses semantic invocation ids. */
+    resetTranscript(): void;
+    resetViewport(): void;
+    clearViewportPointerState(): void;
+    setViewportOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
+    viewportInputGeometryReady(width: number, height: number): boolean;
+    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): SessionViewportInputResult;
+    layoutRoot(): PiTuiLayoutNode;
+    transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
+    exitTranscript(width: number): string;
+    appendWorkflowStatus(message: string): void;
+    appendWorkflowMessage(message: PiWorkflowMessage): void;
+    appendWorkflowResult(result: PiWorkflowResult): void;
+    appendDaxnuts(): void;
+    toggleThinkingVisibility(): void;
+    get toolsExpanded(): boolean;
+    setToolsExpanded(expanded: boolean): void;
+    setExtensionWidget(key: string, component: PiShellComponentPort | null, placement: "aboveEditor" | "belowEditor"): void;
+    setExtensionHeader(component: PiShellComponentPort | null): void;
+    setExtensionFooter(component: PiShellComponentPort | null): void;
+    setExtensionStatus(key: string, text: string | undefined): void;
+    setExtensionWorking(message: string | undefined, visible?: boolean): void;
+    hotkeysPresentation(): PiShellHotkeysPresentation;
+    resetWorkflowPresentation(): void;
+    resetExtensionUi(): void;
+    addExtensionNotification(message: string, type: "info" | "warning" | "error"): void;
+    extensionFooterData(): unknown;
+    usesDefaultInputSurface(): boolean;
+    inputCoordinationSurface(): PiTuiInputSurfaceKind;
+    viewportCompositionEvidence(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+    transcriptRenderCount(): number;
+    setFooterLevel(visible: boolean): void;
+    setInputSurface(component: PiShellComponentPort | null, disposePrevious?: boolean, coordination?: Exclude<PiTuiInputSurfaceKind, "editor">): void;
+    handleInput(data: string): void;
+    invalidate(): void;
+    setFocused(focused: boolean): void;
+    dispose(): void;
+}
+export declare function shellResourceEntries(backend: OwnedUiBackendPort): readonly PiShellResourceEntry[];
+export {};