@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.368

package/dist/integrations/pi/session-ui/prompt-chips.d.ts

@@ -30,6 +30,36 @@ export declare class PromptChipStore {
         target: string;
     }[];
     expandCopiedText(text: string): string;
+    /**
+     * Recall-safe history text. Text / URL / file / folder chips expand to their resolved value
+     * so a restart can reuse them without the originating chip cache. Image chip tags are
+     * preserved verbatim so the sidecar-backed rehydration path can re-render them into live
+     * chips carrying the original attachment bytes.
+     */
     prepareHistoryText(text: string): string;
+    /**
+     * Extract the image chip attachments referenced by an editor draft in occurrence order,
+     * paired with their sidecar identifier. Callers use this to persist image sidecars before a
+     * history row commits, so a fresh process can rehydrate the same chip layout. Unresolved
+     * pending pastes and non-image chips are skipped; caller is responsible for waiting on
+     * pending readiness before this point.
+     */
+    imageChipAttachments(text: string): {
+        readonly id: string;
+        readonly tag: string;
+        readonly image: PromptImageAttachment;
+    }[];
+    /**
+     * Rehydrate a durable recall value into an editor-ready draft: image chip tags are looked up
+     * against a caller-supplied sidecar resolver, and detectable URL / file / folder / large text
+     * substrings are re-registered as atomic chips through the same identity rules the paste path
+     * uses. Image chips whose sidecar returns null are silently stripped without a placeholder.
+     *
+     * Every chip returned is registered in the session `#chips` map so atomic-range,
+     * hyperlink-range, and submission-expansion paths behave identically to a freshly typed draft.
+     * Callers should treat the returned string as programmatic editor text, not another draft to
+     * scan.
+     */
+    rehydrateHistoryText(text: string, resolveImage: (id: string) => PromptImageAttachment | null): string;
     prepareSubmission(text: string): PreparedPrompt;
 }

package/dist/integrations/pi/session-ui/prompt-chips.js

@@ -9,7 +9,13 @@ import { prepareTextPaste } from "./text-paste.js";
 const CHIP_PATTERN = /\[(?:paste #\d+ (?:\+\d+ lines|\d+ chars)|📷 [^\]]+|📁 [^\]]+|📄 [^\]]+|🖼 {1,2}[^\]]+|🔗 [^\]]+)\]/gu;
 const IMAGE_EXTENSION = /\.(?:jpe?g|png|webp|gif|bmp|tiff?)$/iu;
 const URL_PATTERN = /^https?:\/\/[^\s\u0000-\u001f\u007f]+$/iu;
+const URL_SUBSTRING_PATTERN = /https?:\/\/[^\s\u0000-\u001f\u007f\]]+/giu;
+const IMAGE_CHIP_IDENTIFIER_PATTERN = /^\[📷 screenshot-([a-f0-9]+)(?:-resized)?\]$/u;
 const URL_DISPLAY_LENGTH = 40;
+function imageChipIdentifier(tag) {
+    const match = IMAGE_CHIP_IDENTIFIER_PATTERN.exec(tag);
+    return match === null ? null : match[1] ?? null;
+}
 /** Owns semantic chips and bounded pending paste references; cancels background work on reset or disposal. */
 export class PromptChipStore {
     #chips = new Map();
@@ -208,8 +214,129 @@ export class PromptChipStore {
     expandCopiedText(text) {
         return this.#replaceResolvable(text, false).text;
     }
+    /**
+     * Recall-safe history text. Text / URL / file / folder chips expand to their resolved value
+     * so a restart can reuse them without the originating chip cache. Image chip tags are
+     * preserved verbatim so the sidecar-backed rehydration path can re-render them into live
+     * chips carrying the original attachment bytes.
+     */
     prepareHistoryText(text) {
-        return this.#replaceResolvable(text, false, true).text.trim();
+        return this.#replaceResolvable(text, false, false).text.trim();
+    }
+    /**
+     * Extract the image chip attachments referenced by an editor draft in occurrence order,
+     * paired with their sidecar identifier. Callers use this to persist image sidecars before a
+     * history row commits, so a fresh process can rehydrate the same chip layout. Unresolved
+     * pending pastes and non-image chips are skipped; caller is responsible for waiting on
+     * pending readiness before this point.
+     */
+    imageChipAttachments(text) {
+        const results = [];
+        const seen = new Set();
+        for (const match of text.matchAll(CHIP_PATTERN)) {
+            const tag = match[0];
+            if (seen.has(tag))
+                continue;
+            const chip = this.#chips.get(tag);
+            if (chip === undefined || chip.kind !== "image")
+                continue;
+            const identifier = imageChipIdentifier(tag);
+            if (identifier === null)
+                continue;
+            seen.add(tag);
+            results.push({ id: identifier, tag, image: chip.image });
+        }
+        return results;
+    }
+    /**
+     * Rehydrate a durable recall value into an editor-ready draft: image chip tags are looked up
+     * against a caller-supplied sidecar resolver, and detectable URL / file / folder / large text
+     * substrings are re-registered as atomic chips through the same identity rules the paste path
+     * uses. Image chips whose sidecar returns null are silently stripped without a placeholder.
+     *
+     * Every chip returned is registered in the session `#chips` map so atomic-range,
+     * hyperlink-range, and submission-expansion paths behave identically to a freshly typed draft.
+     * Callers should treat the returned string as programmatic editor text, not another draft to
+     * scan.
+     */
+    rehydrateHistoryText(text, resolveImage) {
+        if (!text)
+            return text;
+        // Rationale: resolve image chip tags in-place before further classification. Sidecar hits
+        // register a live image chip; misses silently strip the tag (no placeholder, no notice) per
+        // the durability contract.
+        CHIP_PATTERN.lastIndex = 0;
+        const resolvedImages = text.replace(CHIP_PATTERN, tag => {
+            const identifier = imageChipIdentifier(tag);
+            if (identifier === null)
+                return tag;
+            const attachment = resolveImage(identifier);
+            if (attachment === null)
+                return "";
+            this.#chips.set(tag, { kind: "image", tag, image: attachment });
+            return tag;
+        });
+        // Rationale: split around any surviving image tags so paste-time classification runs on the
+        // intervening prose exactly as it would on a fresh clipboard payload, plus a substring URL
+        // scan so embedded links become atomic chips even in the middle of surrounding text.
+        CHIP_PATTERN.lastIndex = 0;
+        const segments = [];
+        let cursor = 0;
+        for (const match of resolvedImages.matchAll(CHIP_PATTERN)) {
+            const index = match.index ?? cursor;
+            if (index > cursor)
+                segments.push(resolvedImages.slice(cursor, index));
+            segments.push(match[0]);
+            cursor = index + match[0].length;
+        }
+        if (cursor < resolvedImages.length)
+            segments.push(resolvedImages.slice(cursor));
+        CHIP_PATTERN.lastIndex = 0;
+        return segments.map(segment => {
+            if (segment.length === 0 || CHIP_PATTERN.test(segment)) {
+                CHIP_PATTERN.lastIndex = 0;
+                return segment;
+            }
+            CHIP_PATTERN.lastIndex = 0;
+            // Invariant: preserve original whitespace framing so the concatenated recall value
+            // remains stable across rehydration.
+            const leading = segment.match(/^\s+/)?.[0] ?? "";
+            const trailing = segment.match(/\s+$/)?.[0] ?? "";
+            const body = segment.slice(leading.length, segment.length - trailing.length);
+            if (body.length === 0)
+                return segment;
+            // Rationale: substring URL rehydration reuses paste-time URL classification and identity
+            // rules, producing a URL chip whenever a bare http(s) URL appears in the prose. Whole-text
+            // classification runs afterwards to catch path / large-paste candidates that consume the
+            // entire remaining body.
+            const withUrlChips = this.#rehydrateUrlSubstrings(body);
+            if (withUrlChips !== body)
+                return `${leading}${withUrlChips}${trailing}`;
+            const classified = this.transformPastedContent({ kind: "text", text: body });
+            return `${leading}${classified}${trailing}`;
+        }).join("");
+    }
+    #rehydrateUrlSubstrings(body) {
+        let output = "";
+        let cursor = 0;
+        URL_SUBSTRING_PATTERN.lastIndex = 0;
+        for (;;) {
+            const match = URL_SUBSTRING_PATTERN.exec(body);
+            if (match === null)
+                break;
+            const url = match[0];
+            if (match.index > cursor)
+                output += body.slice(cursor, match.index);
+            const label = url.length <= URL_DISPLAY_LENGTH ? url : `${url.slice(0, URL_DISPLAY_LENGTH)}…`;
+            output += this.#recordUnique({ kind: "url", tag: `[🔗 ${label}]`, label, url });
+            cursor = match.index + url.length;
+        }
+        URL_SUBSTRING_PATTERN.lastIndex = 0;
+        if (cursor === 0)
+            return body;
+        if (cursor < body.length)
+            output += body.slice(cursor);
+        return output;
     }
     prepareSubmission(text) {
         const expanded = this.#replaceResolvable(text, true);

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

@@ -10,6 +10,10 @@ export declare class PromptHistoryController {
         fallback: readonly string[];
         active(): boolean;
         render(): void;
+        /** Applied to every recall text before it enters the editor recall list. Callers use this
+         * to re-classify durable chip content back into atomic chips; the identity map returned by
+         * default keeps historical behavior for callers that opt out. */
+        rehydrate?: (text: string) => string;
     };
     constructor(options: {
         editor: PiShellEditorPort;
@@ -18,6 +22,10 @@ export declare class PromptHistoryController {
         fallback: readonly string[];
         active(): boolean;
         render(): void;
+        /** Applied to every recall text before it enters the editor recall list. Callers use this
+         * to re-classify durable chip content back into atomic chips; the identity map returned by
+         * default keeps historical behavior for callers that opt out. */
+        rehydrate?: (text: string) => string;
     });
     start(): void;
     capture(text: string, kind: PromptHistoryKind, cwd: string, sessionId: string): void;

package/dist/integrations/pi/session-ui/prompt-history-controller.js

@@ -7,6 +7,7 @@ export class PromptHistoryController {
     #unsubscribe;
     #snapshot;
     #fallback;
+    #rehydrateCache;
     #disposed = false;
     #generation = 0;
     #unsubscribeSnapshot;
@@ -18,6 +19,7 @@ export class PromptHistoryController {
         if (options.editor.recall === undefined)
             throw new Error("The selected editor does not expose typed history");
         this.#snapshot = { revision: 0, limit: options.limit, entries: [] };
+        this.#rehydrateCache = new Map();
         this.#fallback = boundedTexts([...options.fallback].reverse(), options.limit);
         this.#unsubscribeSnapshot = this.#subscribeSnapshot();
         this.#unsubscribeFailure = options.store.onFailure(() => {
@@ -71,17 +73,43 @@ export class PromptHistoryController {
     synchronize() {
         if (this.#disposed || !this.options.active())
             return;
-        const values = [...this.#local.values()].reverse().map(item => item.text)
-            .concat(this.#snapshot.entries.map(item => item.text), this.#fallback);
+        const local = [...this.#local.values()].reverse().map(item => item.text);
+        const saved = this.#snapshot.entries.map(item => item.text);
+        const values = this.#rehydrateAll(local.concat(saved, this.#fallback));
         this.options.editor.recall.replace(boundedTexts(values, this.#snapshot.limit));
         this.options.render();
     }
+    #rehydrateAll(values) {
+        const rehydrate = this.options.rehydrate;
+        if (rehydrate === undefined)
+            return [...values];
+        const cache = this.#rehydrateCache;
+        const results = [];
+        for (const value of values) {
+            const cached = cache.get(value);
+            if (cached !== undefined) {
+                results.push(cached);
+                continue;
+            }
+            const rendered = rehydrate(value);
+            cache.set(value, rendered);
+            results.push(rendered);
+        }
+        if (cache.size > 512) {
+            // Performance: keep the cache bounded so long sessions cannot grow it without limit.
+            const keys = [...cache.keys()].slice(0, cache.size - 256);
+            for (const key of keys)
+                cache.delete(key);
+        }
+        return results;
+    }
     reset(fallback) {
         this.#generation++;
         this.#unsubscribeSnapshot();
         this.#unsubscribeSnapshot = this.#subscribeSnapshot();
         this.#fallback = boundedTexts([...fallback].reverse(), this.options.limit);
         this.#local.clear();
+        this.#rehydrateCache.clear();
         this.options.editor.recall.reset();
         this.synchronize();
         this.options.store.refresh();

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

@@ -1,6 +1,7 @@
-import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState } from "../../../contracts/owned-ui/index.js";
+import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState, type SuggestionDecision, type SuggestionDecisionReason, type SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
 export interface ContextualPromptSuggestionSurface {
     canPresent(identity: OwnedUiPromptSuggestionIdentity): boolean;
+    presentationBlockReason?(identity: OwnedUiPromptSuggestionIdentity): SuggestionDecision;
     present(text: string): boolean;
     clear(): void;
     requestRender(): void;
@@ -10,18 +11,25 @@ export interface ContextualPromptSuggestionControllerOptions {
     readonly surface: ContextualPromptSuggestionSurface;
     readonly enabled: boolean;
     readonly timeoutMs?: number;
+    readonly diagnostics?: SuggestionDiagnosticObserver;
+    readonly now?: () => number;
 }
-/** Prefetches one candidate, holds it invisibly, and publishes only after matching settlement. */
+type DecisionIdentity = Omit<OwnedUiPromptSuggestionIdentity, "model"> & {
+    readonly model: OwnedUiPromptSuggestionIdentity["model"] | null;
+};
+/** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
 export declare class ContextualPromptSuggestionController {
     #private;
     readonly options: ContextualPromptSuggestionControllerOptions;
     constructor(options: ContextualPromptSuggestionControllerOptions);
     get state(): OwnedUiPromptSuggestionState;
     setEnabled(enabled: boolean): void;
-    consider(identity: OwnedUiPromptSuggestionIdentity, eligible: boolean): void;
+    skip(identity: DecisionIdentity, reason: SuggestionDecisionReason): void;
+    consider(identity: OwnedUiPromptSuggestionIdentity, decision: boolean | SuggestionDecision): void;
     settle(identity: OwnedUiPromptSuggestionIdentity): void;
     accept(): void;
     invalidate(): void;
     dispose(): void;
 }
 export declare function samePromptSuggestionIdentity(left: OwnedUiPromptSuggestionIdentity, right: OwnedUiPromptSuggestionIdentity): boolean;
+export {};

package/dist/integrations/pi/session-ui/prompt-suggestion-controller.js

@@ -1,18 +1,22 @@
 import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
-/** Prefetches one candidate, holds it invisibly, and publishes only after matching settlement. */
+/** Prefetches one inert candidate; owns retirement even when a provider ignores abort. */
 export class ContextualPromptSuggestionController {
     options;
     #state = { status: "idle" };
-    #epoch = 0;
-    #abort = null;
+    #request = null;
     #lastConsidered = "";
     #enabled;
     #disposed = false;
+    #sessionKey = "";
+    #sessionSequence = 0;
+    #requestSequence = 0;
     #timeoutMs;
+    #now;
     constructor(options) {
         this.options = options;
         this.#enabled = options.enabled;
         this.#timeoutMs = options.timeoutMs ?? 15_000;
+        this.#now = options.now ?? Date.now;
     }
     get state() { return this.#state; }
     setEnabled(enabled) {
@@ -21,103 +25,174 @@ export class ContextualPromptSuggestionController {
         this.#enabled = enabled;
         this.invalidate();
     }
-    consider(identity, eligible) {
+    skip(identity, reason) {
+        this.invalidate();
+        this.#emit(this.#metadata(identity), "skipped", reason);
+    }
+    consider(identity, decision) {
         const key = identityKey(identity);
         if (key === this.#lastConsidered)
             return;
         this.#lastConsidered = key;
         this.invalidate();
-        if (!this.#enabled || this.#disposed || !eligible)
+        const reason = this.#disposed ? "disposed" : !this.#enabled ? "disabled"
+            : decision === false ? "ineligible" : decision === true ? null : decision;
+        if (reason !== null) {
+            this.#emit(this.#metadata(identity), "skipped", reason);
             return;
-        const epoch = this.#epoch;
-        const abort = new AbortController();
-        this.#abort = abort;
+        }
+        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 };
-        const timeout = setTimeout(() => {
-            abort.abort();
-            if (this.#epoch === epoch && this.#state.status === "generating") {
-                this.#abort = null;
-                this.#state = { status: "idle" };
-            }
+        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);
-        timeout.unref?.();
-        void this.options.generator.generate({ identity, signal: abort.signal })
-            .then(result => this.#receive(epoch, identity, result))
-            .catch(() => this.#fail(epoch))
-            .finally(() => {
-            clearTimeout(timeout);
-            if (this.#epoch === epoch)
-                this.#abort = null;
-        });
+        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);
+        }
     }
     settle(identity) {
         if (this.#disposed || !this.#enabled || this.#state.status === "idle")
             return;
         if (!samePromptSuggestionIdentity(this.#state.identity, identity)) {
+            if (this.#request)
+                this.#finish(this.#request, "stale-result", "stale-identity");
             this.invalidate();
             return;
         }
-        if (this.#state.status === "generating") {
+        if (this.#state.status === "generating")
             this.#state = { ...this.#state, settled: true };
-            return;
-        }
-        if (this.#state.status === "prepared")
-            this.#show(identity, this.#state.text);
-    }
-    accept() {
-        this.#invalidate(false);
-    }
-    invalidate() {
-        this.#invalidate(true);
+        else if (this.#state.status === "prepared" && this.#request)
+            this.#show(this.#request, this.#state.text);
     }
+    accept() { this.#invalidate(false); }
+    invalidate() { this.#invalidate(true); }
     dispose() {
         this.#disposed = true;
         this.invalidate();
+        this.#lastConsidered = "";
+        this.#sessionKey = "";
     }
     #invalidate(clearSurface) {
         const hadVisibleSuggestion = this.#state.status === "available";
-        this.#epoch += 1;
-        this.#abort?.abort();
-        this.#abort = null;
+        const request = this.#request;
+        if (request)
+            this.#finish(request, "cancelled");
+        this.#request = null;
         this.#state = { status: "idle" };
+        request?.abort.abort();
         if (clearSurface && hadVisibleSuggestion) {
             this.options.surface.clear();
             this.options.surface.requestRender();
         }
     }
-    #fail(epoch) {
-        if (this.#epoch !== epoch)
+    #failed(request) {
+        if (this.#request !== request || request.terminal) {
+            this.#late(request);
             return;
-        this.#abort = null;
+        }
+        this.#finish(request, "provider-failure");
+        this.#request = null;
         this.#state = { status: "idle" };
     }
-    #receive(epoch, identity, result) {
-        assertOwnedUiPromptSuggestionResult(result);
-        if (this.#disposed || !this.#enabled || this.#epoch !== epoch || this.#state.status !== "generating")
+    #receive(request, result) {
+        if (this.#disposed || this.#request !== request || request.terminal || this.#state.status !== "generating") {
+            this.#late(request);
             return;
-        if (!samePromptSuggestionIdentity(identity, result.identity)) {
+        }
+        try {
+            assertOwnedUiPromptSuggestionResult(result);
+        }
+        catch {
+            this.#finish(request, "rejected");
+            this.invalidate();
+            return;
+        }
+        if (!samePromptSuggestionIdentity(request.identity, result.identity)) {
+            this.#finish(request, "stale-result", "stale-identity");
+            this.invalidate();
+            return;
+        }
+        if (result.outcome !== "candidate") {
+            this.#finish(request, result.outcome);
             this.invalidate();
             return;
         }
         const text = normalizePromptSuggestionCandidate(result.text);
         if (text === null) {
-            this.#fail(epoch);
+            this.#finish(request, "rejected");
+            this.invalidate();
             return;
         }
-        this.#abort = null;
+        clearTimeout(request.timer);
         if (this.#state.settled)
-            this.#show(identity, text);
+            this.#show(request, text);
         else
-            this.#state = { status: "prepared", identity, text };
+            this.#state = { status: "prepared", identity: request.identity, text };
     }
-    #show(identity, text) {
-        if (!this.options.surface.canPresent(identity) || !this.options.surface.present(text)) {
+    #show(request, text) {
+        const reason = this.options.surface.presentationBlockReason?.(request.identity)
+            ?? (this.options.surface.canPresent(request.identity) ? null : "presentation-unavailable");
+        if (reason !== null || !this.options.surface.present(text)) {
+            this.#finish(request, "presentation-blocked", reason ?? "presentation-unavailable");
             this.invalidate();
             return;
         }
-        this.#state = { status: "available", identity, text };
+        this.#state = { status: "available", identity: request.identity, text };
+        this.#finish(request, "displayed");
         this.options.surface.requestRender();
     }
+    #finish(request, event, reason) {
+        if (request.terminal)
+            return;
+        // Concurrency: retire before notifying observers or aborting; neither may rewrite the winner.
+        request.terminal = true;
+        clearTimeout(request.timer);
+        this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, event, reason);
+    }
+    #late(request) {
+        if (!this.#disposed)
+            this.#emit({ ...request.metadata, elapsedMs: Math.max(0, this.#now() - request.startedAt) }, "late-result-discarded");
+    }
+    #metadata(identity) {
+        const key = `${identity.sessionId}\0${identity.sessionGeneration}`;
+        if (this.#sessionKey !== key) {
+            this.#sessionKey = key;
+            this.#sessionSequence++;
+        }
+        return {
+            event: "skipped", session: this.#sessionSequence, run: identity.runSequence, response: identity.responseSequence,
+            request: 0, provider: identity.model?.providerId ?? "", model: identity.model?.modelId ?? "",
+            reasoning: "unavailable", elapsedMs: 0,
+        };
+    }
+    #emit(metadata, event, reason) {
+        try {
+            this.options.diagnostics?.record({ ...metadata, event, ...(reason === undefined ? {} : { reason }) });
+        }
+        catch { /* Security: diagnostics never own input or lifecycle. */ }
+    }
 }
 export function samePromptSuggestionIdentity(left, right) {
     return left.sessionId === right.sessionId

package/dist/integrations/pi/session-ui/session-shell-root.d.ts

@@ -1,4 +1,5 @@
-import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort } from "../../../contracts/owned-ui/index.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
+import type { PiTuiPointerSurface } from "../tui-runtime/index.js";
 import type { UiRouteHost } from "../../../ui/apps/index.js";
 import { type TranscriptViewportFrame, type TranscriptViewportFrameDescriptor } from "../../../ui/components/index.js";
 import { type PiEngineAdapter, type PiWorkflowMessage, type PiWorkflowResult } from "../engine/index.js";
@@ -22,6 +23,10 @@ export interface OwnedUiSessionShellOptions {
         readonly store: import("../../../contracts/owned-ui/index.js").PromptHistoryPort;
         readonly limit: number;
         readonly editor: import("../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;
     };
     readonly backend: OwnedUiBackendPort;
     readonly cwd: string;
@@ -45,6 +50,7 @@ export interface OwnedUiSessionShellOptions {
     };
     /** Optional deterministic seam for keyboard scheduling and phase evidence. */
     readonly promptSuggestions?: {
+        readonly diagnostics?: SuggestionDiagnosticObserver;
         readonly generator: OwnedUiPromptSuggestionGeneratorPort;
         readonly enabled: () => boolean;
         readonly onChange: (listener: (enabled: boolean) => void) => () => void;
@@ -99,12 +105,24 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     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;
     disposePendingPastes(): Promise<void>;
+    promptSuggestionPrepareBlockReason(): SuggestionDecision;
     canPreparePromptSuggestion(): boolean;
+    promptSuggestionPresentationBlockReason(): SuggestionDecision;
     canPresentPromptSuggestion(): boolean;
     setPromptSuggestion(text: string | null): void;
     update(view: OwnedUiSessionViewModel): void;
@@ -147,9 +165,13 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setViewportConfig(config: OwnedUiViewportSettings): 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;
-    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number): {
+    setViewportOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
+    viewportInputGeometryReady(width: number, height: number): boolean;
+    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): {
         readonly data: string;
         readonly consumed: boolean;
         readonly copyText?: string;