@timurproko/a1 0.1.8-dev.269 → 0.1.8-dev.277

package/dist/integrations/pi/components/upstream/components/owned-editor.js

@@ -1,9 +1,11 @@
 /**
  * Adapted from @earendil-works/pi-coding-agent 0.84.2
  * packages/coding-agent/src/modes/interactive/components/custom-editor.ts (MIT).
- * Modifications: A1-owned class name and A1-owned synchronized keybinding contract.
+ * Modifications: A1-owned class name, synchronized keybinding contract, and a semantic
+ * bare-A1 prompt-prefix/contextual-suggestion presentation branch.
  */
-import { Editor } from "#pi-tui";
+import { CURSOR_MARKER, Editor, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "#pi-tui";
+const PROMPT_GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 export class OwnedEditor extends Editor {
     keybindings;
     actionHandlers = new Map();
@@ -11,14 +13,63 @@ export class OwnedEditor extends Editor {
     onCtrlD;
     onPasteImage;
     onExtensionShortcut;
-    constructor(tui, theme, keybindings, options) {
+    onPromptSuggestionAccepted;
+    #promptSuggestion = null;
+    #promptPrefix;
+    #styleSuggestion;
+    #styleSuggestionCaret;
+    #terminalRows;
+    constructor(tui, theme, keybindings, options = {}) {
         super(tui, theme, options);
         this.keybindings = keybindings;
+        this.#promptPrefix = options.promptPrefix ?? "";
+        this.#styleSuggestion = options.styleSuggestion ?? (text => text);
+        this.#styleSuggestionCaret = options.styleSuggestionCaret ?? (text => `\u001b[7m${text}\u001b[27m`);
+        this.#terminalRows = options.terminalRows ?? (() => 24);
+    }
+    setPromptSuggestion(text) {
+        this.#promptSuggestion = text;
+    }
+    canPresentPromptSuggestion() {
+        return this.#promptPrefix.length > 0
+            && this.focused
+            && !this.disableSubmit
+            && this.getText().length === 0
+            && !this.isShowingAutocomplete();
+    }
+    setText(text) {
+        if (text.length > 0)
+            this.#promptSuggestion = null;
+        super.setText(text);
+    }
+    render(width) {
+        if (this.#promptPrefix.length === 0)
+            return super.render(width);
+        if (this.#promptSuggestion !== null && this.canPresentPromptSuggestion()) {
+            return this.#renderSuggestion(width);
+        }
+        return this.#renderPrefixedEditor(width);
     }
     onAction(action, handler) { this.actionHandlers.set(action, handler); }
     handleInput(data) {
         if (this.onExtensionShortcut?.(data))
             return;
+        if (this.#promptSuggestion !== null
+            && !this.isShowingAutocomplete()
+            && this.canPresentPromptSuggestion()
+            && this.keybindings.matches(data, "tui.input.submit")) {
+            return;
+        }
+        if (this.#promptSuggestion !== null
+            && !this.isShowingAutocomplete()
+            && this.canPresentPromptSuggestion()
+            && this.keybindings.matches(data, "tui.input.tab")) {
+            const accepted = this.#promptSuggestion;
+            this.#promptSuggestion = null;
+            super.setText(accepted);
+            this.onPromptSuggestionAccepted?.(accepted);
+            return;
+        }
         if (this.keybindings.matches(data, "app.clipboard.pasteImage")) {
             this.onPasteImage?.();
             return;
@@ -52,4 +103,52 @@ export class OwnedEditor extends Editor {
         }
         super.handleInput(data);
     }
+    #renderSuggestion(width) {
+        const prefixWidth = visibleWidth(this.#promptPrefix);
+        const innerWidth = Math.max(1, width - prefixWidth);
+        const maxPadding = Math.max(0, Math.floor((innerWidth - 1) / 2));
+        const paddingX = Math.min(this.getPaddingX(), maxPadding);
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));
+        const chunks = wrapTextWithAnsi(this.#promptSuggestion ?? "", layoutWidth).map(text => ({ text }));
+        const maxVisible = Math.max(5, Math.floor(this.#terminalRows() * 0.3));
+        const visible = chunks.slice(0, maxVisible);
+        const horizontal = this.borderColor("─".repeat(Math.max(0, width)));
+        const leftPadding = " ".repeat(paddingX);
+        const rightPadding = leftPadding;
+        const rows = visible.map((chunk, index) => {
+            let content;
+            if (index === 0) {
+                const first = [...PROMPT_GRAPHEMES.segment(chunk.text)][0]?.segment ?? " ";
+                const remaining = chunk.text.slice(first === " " && chunk.text.length === 0 ? 0 : first.length);
+                const marker = this.focused ? CURSOR_MARKER : "";
+                content = `${marker}${this.#styleSuggestionCaret(first)}${this.#styleSuggestion(remaining)}`;
+            }
+            else {
+                content = this.#styleSuggestion(chunk.text);
+            }
+            const plainWidth = visibleWidth(chunk.text);
+            const padding = " ".repeat(Math.max(0, contentWidth - plainWidth));
+            const prefix = index === 0 ? this.#promptPrefix : " ".repeat(prefixWidth);
+            return truncateToWidth(`${prefix}${leftPadding}${content}${padding}${rightPadding}`, width);
+        });
+        return [horizontal, ...rows, horizontal];
+    }
+    #renderPrefixedEditor(width) {
+        const prefixWidth = visibleWidth(this.#promptPrefix);
+        const innerWidth = Math.max(1, width - prefixWidth);
+        const rows = super.render(innerWidth);
+        const maxPadding = Math.max(0, Math.floor((innerWidth - 1) / 2));
+        const paddingX = Math.min(this.getPaddingX(), maxPadding);
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));
+        const layoutCount = this.getLines().flatMap(line => wrapTextWithAnsi(line, layoutWidth)).length || 1;
+        const visibleCount = Math.min(layoutCount, Math.max(5, Math.floor(this.#terminalRows() * 0.3)));
+        const bottomBorder = visibleCount + 1;
+        return rows.map((row, index) => {
+            if (index === 0 || index === bottomBorder)
+                return `${row}${this.borderColor("─".repeat(prefixWidth))}`;
+            return `${index === 1 ? this.#promptPrefix : " ".repeat(prefixWidth)}${row}`;
+        });
+    }
 }

package/dist/integrations/pi/engine/adapter.d.ts

@@ -1,6 +1,6 @@
 import type { PiSessionForkPrompt, PiSessionSelection } from "./session-selection.js";
 import { type AgentSessionRuntime, type AgentSessionServices, type SessionInfo } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiImageAttachment, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../../../contracts/owned-ui/index.js";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiImageAttachment, type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionRequest, type OwnedUiPromptSuggestionResult, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../../../contracts/owned-ui/index.js";
 import { type PiAuthenticationProviderOption, type PiBashWorkflowResult, type PiPinnedSettingsCallback, type PiPinnedSettingsSnapshot, type PiWorkflowAutocompleteCommand, type PiWorkflowHost, type PiWorkflowInteractionHost, type PiWorkflowOption, type PiWorkflowRequest, type PiWorkflowResult } from "./workflows.js";
 import { PiSettingsIntegration } from "./settings-integration.js";
 import type { PiSettingOwnerHandlers } from "./settings-effects.js";
@@ -127,7 +127,7 @@ export interface AdapterCommandResult {
     readonly diagnostic: string | null;
 }
 /** Owns the pinned Pi session lifecycle and translates its events into the neutral agent-engine contract. */
-export declare class PiEngineAdapter {
+export declare class PiEngineAdapter implements OwnedUiPromptSuggestionGeneratorPort {
     #private;
     constructor(options?: PiEngineAdapterOptions);
     setWorkflowInteractionHost(interaction: PiWorkflowInteractionHost): void;
@@ -139,6 +139,7 @@ export declare class PiEngineAdapter {
     currentSessionFile(): string | null;
     currentSessionResumeMetadata(): PiSessionResumeMetadata | null;
     get disposed(): boolean;
+    generate(request: OwnedUiPromptSuggestionRequest): Promise<OwnedUiPromptSuggestionResult>;
     start(): Promise<OwnedUiSessionViewModel>;
     onEvent(listener: (event: OwnedUiEvent) => void): () => void;
     flushEvents(): Promise<void>;

package/dist/integrations/pi/engine/adapter.js

@@ -8,7 +8,7 @@ import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../../product-identity.js";
 import { configureOwnedHttpDispatcher } from "./http-dispatcher.js";
 import { copyToClipboard, CredentialSynchronizationError, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiSnapshot, } from "../../../contracts/owned-ui/index.js";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiPromptSuggestionRequest, assertOwnedUiPromptSuggestionResult, assertOwnedUiSnapshot, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
@@ -129,6 +129,8 @@ export class PiEngineAdapter {
     #eventQueueProcessing;
     #droppedEventCount = 0;
     #agentRunActive = false;
+    #agentRunSequence = 0;
+    #assistantResponseSequence = 0;
     #statusKind = null;
     #sessionCommands;
     #gitBranch = null;
@@ -200,6 +202,69 @@ export class PiEngineAdapter {
     get disposed() {
         return this.#disposed;
     }
+    async generate(request) {
+        assertOwnedUiPromptSuggestionRequest(request);
+        const identity = request.identity;
+        const session = this.#session;
+        const runtime = this.#runtime;
+        const activeModel = this.#activeModel;
+        if (this.#disposed || session === undefined || runtime === undefined || request.signal.aborted
+            || identity.sessionId !== this.#sessionId
+            || identity.sessionGeneration !== this.#sessionGeneration
+            || identity.runSequence !== this.#agentRunSequence
+            || identity.responseSequence !== this.#assistantResponseSequence
+            || activeModel === null
+            || identity.model.providerId !== activeModel.providerId
+            || identity.model.modelId !== activeModel.modelId) {
+            return { identity, text: null };
+        }
+        const model = session.model;
+        const agentState = session.agent.state;
+        if (model === undefined || typeof runtime.services.modelRuntime.completeSimple !== "function") {
+            return { identity, text: null };
+        }
+        const messages = agentState.messages.filter(message => message.role === "user" || message.role === "assistant" || message.role === "toolResult");
+        const reasoning = session.thinkingLevel === "minimal"
+            || session.thinkingLevel === "low"
+            || session.thinkingLevel === "medium"
+            || session.thinkingLevel === "high"
+            || session.thinkingLevel === "xhigh"
+            || session.thinkingLevel === "max"
+            ? session.thinkingLevel
+            : undefined;
+        const response = await runtime.services.modelRuntime.completeSimple(model, {
+            systemPrompt: agentState.systemPrompt,
+            messages: [
+                ...messages,
+                { role: "user", content: CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, timestamp: Date.now() },
+            ],
+            tools: agentState.tools,
+        }, {
+            signal: request.signal,
+            ...(reasoning === undefined ? {} : { reasoning }),
+        });
+        if (isRecord(response)
+            && (stringValue(response.errorMessage) !== undefined
+                || stringValue(response.stopReason) === "error"
+                || stringValue(response.stopReason) === "aborted")) {
+            const result = { identity, text: null };
+            assertOwnedUiPromptSuggestionResult(result);
+            return result;
+        }
+        const content = Array.isArray(response.content) ? response.content : [];
+        if (content.some(block => isRecord(block) && block.type === "toolCall")) {
+            const result = { identity, text: null };
+            assertOwnedUiPromptSuggestionResult(result);
+            return result;
+        }
+        const textBlock = content.find(block => isRecord(block) && block.type === "text" && typeof block.text === "string");
+        const result = {
+            identity,
+            text: normalizePromptSuggestionCandidate(isRecord(textBlock) && typeof textBlock.text === "string" ? textBlock.text : null),
+        };
+        assertOwnedUiPromptSuggestionResult(result);
+        return result;
+    }
     async start() {
         if (this.#runtime)
             return this.view();
@@ -1773,6 +1838,8 @@ export class PiEngineAdapter {
         this.#status = { ...this.#status, workingMessage: null, badges: [] };
         this.#statusKind = null;
         this.#agentRunActive = false;
+        this.#agentRunSequence = 0;
+        this.#assistantResponseSequence = 0;
         this.#activeModel = readModel(session.model);
         this.#reconcileActiveModelAvailability();
         this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
@@ -1880,6 +1947,7 @@ export class PiEngineAdapter {
         switch (event.type) {
             case "agent_start":
                 this.#agentRunActive = true;
+                this.#agentRunSequence += 1;
                 this.#emitEvent({ type: "agent-run-started" });
                 this.#enterWorkState("working", "Working");
                 return;
@@ -1906,7 +1974,26 @@ export class PiEngineAdapter {
                 // finalization is intentionally not a substitute: rebuilds, retries,
                 // thinking parts, and tool rows can all finalize independently.
                 if (isRecord(event.message) && event.message.role === "assistant") {
-                    this.#emitEvent({ type: "assistant-message-completed" });
+                    this.#assistantResponseSequence += 1;
+                    const content = Array.isArray(event.message.content) ? event.message.content : [];
+                    const stopReason = stringValue(event.message.stopReason) ?? null;
+                    const toolContinuation = stopReason === "toolUse"
+                        || content.some(item => isRecord(item) && item.type === "toolCall");
+                    const successful = stringValue(event.message.errorMessage) === undefined
+                        && stopReason !== "error"
+                        && stopReason !== "aborted"
+                        && textFromContent(content).trim().length > 0;
+                    this.#emitEvent({
+                        type: "assistant-message-completed",
+                        sessionGeneration: this.#sessionGeneration,
+                        runSequence: this.#agentRunSequence,
+                        responseSequence: this.#assistantResponseSequence,
+                        model: this.#activeModel,
+                        assistantMessageCount: this.#transcript.filter(block => block.kind === "assistant").length,
+                        successful,
+                        stopReason,
+                        toolContinuation,
+                    });
                 }
                 return;
             case "turn_end":
@@ -1951,6 +2038,23 @@ export class PiEngineAdapter {
                     this.#leaveWorkStates();
                 }
                 this.#emitView();
+                if (event.type === "agent_settled") {
+                    const assistants = finalMessages.filter(message => isRecord(message) && message.role === "assistant");
+                    const lastAssistant = assistants.at(-1);
+                    const successful = lastAssistant !== undefined
+                        && stringValue(lastAssistant.errorMessage) === undefined
+                        && stringValue(lastAssistant.stopReason) !== "error"
+                        && stringValue(lastAssistant.stopReason) !== "aborted";
+                    this.#emitEvent({
+                        type: "agent-run-settled",
+                        sessionGeneration: this.#sessionGeneration,
+                        runSequence: this.#agentRunSequence,
+                        responseSequence: this.#assistantResponseSequence,
+                        model: this.#activeModel,
+                        assistantMessageCount: assistants.length,
+                        successful,
+                    });
+                }
                 return;
             }
             case "queue_update": {

package/dist/integrations/pi/engine/conformance.d.ts

@@ -7,7 +7,7 @@ export declare const REQUIRED_PI_CAPABILITY_OPERATIONS: Readonly<{
     readonly "public-exports": readonly ["services.create", "session.create", "runtime.create"];
     readonly "session-lifecycle": readonly ["session.new", "session.resume", "session.rebind", "session.dispose"];
     readonly "commands-events": readonly ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"];
-    readonly "models-authentication": readonly ["models.list", "models.refresh", "auth.status", "auth.login", "auth.logout", "auth.cancel"];
+    readonly "models-authentication": readonly ["models.list", "models.refresh", "models.completeSimple", "auth.status", "auth.login", "auth.logout", "auth.cancel"];
     readonly settings: readonly ["settings.read", "settings.write", "settings.flush"];
     readonly "resources-extensions": readonly ["resources.discover", "extensions.inline", "extensions.bind", "extensions.reload", "renderers.invoke"];
     readonly workflows: readonly ["workflow.route", "workflow.validate", "workflow.diagnostics"];

package/dist/integrations/pi/engine/conformance.js

@@ -9,7 +9,7 @@ export const REQUIRED_PI_CAPABILITY_OPERATIONS = Object.freeze({
     "public-exports": ["services.create", "session.create", "runtime.create"],
     "session-lifecycle": ["session.new", "session.resume", "session.rebind", "session.dispose"],
     "commands-events": ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"],
-    "models-authentication": ["models.list", "models.refresh", "auth.status", "auth.login", "auth.logout", "auth.cancel"],
+    "models-authentication": ["models.list", "models.refresh", "models.completeSimple", "auth.status", "auth.login", "auth.logout", "auth.cancel"],
     settings: ["settings.read", "settings.write", "settings.flush"],
     "resources-extensions": ["resources.discover", "extensions.inline", "extensions.bind", "extensions.reload", "renderers.invoke"],
     workflows: ["workflow.route", "workflow.validate", "workflow.diagnostics"],
@@ -86,7 +86,7 @@ export async function runPiUpgradeConformance() {
             const session = created.session;
             sessionId = session.sessionId;
             requireMethods(session, "session commands", ["prompt", "steer", "followUp", "abort", "compact", "setModel", "setThinkingLevel", "subscribe", "dispose"]);
-            requireMethods(services.modelRuntime, "models/authentication", ["getModels", "getModel", "checkAuth", "login", "logout", "refresh"]);
+            requireMethods(services.modelRuntime, "models/authentication", ["getModels", "getModel", "completeSimple", "checkAuth", "login", "logout", "refresh"]);
             requireMethods(services.settingsManager, "settings", ["getGlobalSettings", "getProjectSettings", "flush"]);
             requireMethods(services.resourceLoader, "resources/extensions", ["getExtensions", "getSkills", "getPrompts", "getThemes", "reload"]);
             const unsubscribe = session.subscribe(() => undefined);

package/dist/integrations/pi/engine/workflow-controllers.d.ts

@@ -17,5 +17,5 @@ export declare class PiWorkflowControllerPort implements AgentWorkflowPort {
     listWorkflows(): Promise<readonly AgentWorkflowDescriptor[]>;
     executeWorkflow(workflowId: string, input: AgentJsonValue, signal?: AbortSignal): Promise<AgentJsonValue>;
 }
-export declare const PI_BUILTIN_WORKFLOW_ROUTES: readonly ("name" | "share" | "model" | "login" | "logout" | "settings" | "reload" | "compact" | "new" | "resume" | "session" | "scoped-models" | "export" | "import" | "copy" | "changelog" | "hotkeys" | "fork" | "clone" | "tree" | "trust" | "quit" | "debug" | "arminsayshi" | "dementedelves")[];
+export declare const PI_BUILTIN_WORKFLOW_ROUTES: readonly ("name" | "share" | "model" | "login" | "logout" | "settings" | "reload" | "compact" | "new" | "resume" | "quit" | "session" | "scoped-models" | "export" | "import" | "copy" | "changelog" | "hotkeys" | "fork" | "clone" | "tree" | "trust" | "debug" | "arminsayshi" | "dementedelves")[];
 export declare const PI_WORKFLOW_CAPABILITIES: readonly WorkflowCapability[];

package/dist/integrations/pi/session-ui/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./prompt-suggestion-controller.js";
 export * from "./session-shell.js";
 export * from "./stream-presentation-coalescer.js";
 export * from "./route-host.js";

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

@@ -1,3 +1,4 @@
+export * from "./prompt-suggestion-controller.js";
 export * from "./session-shell.js";
 export * from "./stream-presentation-coalescer.js";
 export * from "./route-host.js";

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

@@ -0,0 +1,27 @@
+import { type OwnedUiPromptSuggestionGeneratorPort, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionState } from "../../../contracts/owned-ui/index.js";
+export interface ContextualPromptSuggestionSurface {
+    canPresent(identity: OwnedUiPromptSuggestionIdentity): boolean;
+    present(text: string): boolean;
+    clear(): void;
+    requestRender(): void;
+}
+export interface ContextualPromptSuggestionControllerOptions {
+    readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+    readonly surface: ContextualPromptSuggestionSurface;
+    readonly enabled: boolean;
+    readonly timeoutMs?: number;
+}
+/** Prefetches one candidate, holds it invisibly, and publishes only after matching settlement. */
+export declare class ContextualPromptSuggestionController {
+    #private;
+    readonly options: ContextualPromptSuggestionControllerOptions;
+    constructor(options: ContextualPromptSuggestionControllerOptions);
+    get state(): OwnedUiPromptSuggestionState;
+    setEnabled(enabled: boolean): void;
+    consider(identity: OwnedUiPromptSuggestionIdentity, eligible: boolean): void;
+    settle(identity: OwnedUiPromptSuggestionIdentity): void;
+    accept(): void;
+    invalidate(): void;
+    dispose(): void;
+}
+export declare function samePromptSuggestionIdentity(left: OwnedUiPromptSuggestionIdentity, right: OwnedUiPromptSuggestionIdentity): boolean;

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

@@ -0,0 +1,132 @@
+import { assertOwnedUiPromptSuggestionResult, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
+/** Prefetches one candidate, holds it invisibly, and publishes only after matching settlement. */
+export class ContextualPromptSuggestionController {
+    options;
+    #state = { status: "idle" };
+    #epoch = 0;
+    #abort = null;
+    #lastConsidered = "";
+    #enabled;
+    #disposed = false;
+    #timeoutMs;
+    constructor(options) {
+        this.options = options;
+        this.#enabled = options.enabled;
+        this.#timeoutMs = options.timeoutMs ?? 15_000;
+    }
+    get state() { return this.#state; }
+    setEnabled(enabled) {
+        if (this.#enabled === enabled)
+            return;
+        this.#enabled = enabled;
+        this.invalidate();
+    }
+    consider(identity, eligible) {
+        const key = identityKey(identity);
+        if (key === this.#lastConsidered)
+            return;
+        this.#lastConsidered = key;
+        this.invalidate();
+        if (!this.#enabled || this.#disposed || !eligible)
+            return;
+        const epoch = this.#epoch;
+        const abort = new AbortController();
+        this.#abort = abort;
+        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.#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;
+        });
+    }
+    settle(identity) {
+        if (this.#disposed || !this.#enabled || this.#state.status === "idle")
+            return;
+        if (!samePromptSuggestionIdentity(this.#state.identity, identity)) {
+            this.invalidate();
+            return;
+        }
+        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);
+    }
+    dispose() {
+        this.#disposed = true;
+        this.invalidate();
+    }
+    #invalidate(clearSurface) {
+        const hadVisibleSuggestion = this.#state.status === "available";
+        this.#epoch += 1;
+        this.#abort?.abort();
+        this.#abort = null;
+        this.#state = { status: "idle" };
+        if (clearSurface && hadVisibleSuggestion) {
+            this.options.surface.clear();
+            this.options.surface.requestRender();
+        }
+    }
+    #fail(epoch) {
+        if (this.#epoch !== epoch)
+            return;
+        this.#abort = null;
+        this.#state = { status: "idle" };
+    }
+    #receive(epoch, identity, result) {
+        assertOwnedUiPromptSuggestionResult(result);
+        if (this.#disposed || !this.#enabled || this.#epoch !== epoch || this.#state.status !== "generating")
+            return;
+        if (!samePromptSuggestionIdentity(identity, result.identity)) {
+            this.invalidate();
+            return;
+        }
+        const text = normalizePromptSuggestionCandidate(result.text);
+        if (text === null) {
+            this.#fail(epoch);
+            return;
+        }
+        this.#abort = null;
+        if (this.#state.settled)
+            this.#show(identity, text);
+        else
+            this.#state = { status: "prepared", identity, text };
+    }
+    #show(identity, text) {
+        if (!this.options.surface.canPresent(identity) || !this.options.surface.present(text)) {
+            this.invalidate();
+            return;
+        }
+        this.#state = { status: "available", identity, text };
+        this.options.surface.requestRender();
+    }
+}
+export function samePromptSuggestionIdentity(left, right) {
+    return left.sessionId === right.sessionId
+        && left.sessionGeneration === right.sessionGeneration
+        && left.runSequence === right.runSequence
+        && left.responseSequence === right.responseSequence
+        && left.model.providerId === right.model.providerId
+        && left.model.modelId === right.model.modelId;
+}
+function identityKey(identity) {
+    return `${identity.sessionId}\0${identity.sessionGeneration}\0${identity.runSequence}\0${identity.responseSequence}\0${identity.model.providerId}\0${identity.model.modelId}`;
+}

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

@@ -1,4 +1,4 @@
-import type { OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort } from "../../../contracts/owned-ui/index.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort } from "../../../contracts/owned-ui/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";
@@ -39,6 +39,11 @@ export interface OwnedUiSessionShellOptions {
         readonly scheduler?: StreamPresentationScheduler;
     };
     /** Optional deterministic seam for keyboard scheduling and phase evidence. */
+    readonly promptSuggestions?: {
+        readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+        readonly enabled: () => boolean;
+        readonly onChange: (listener: (enabled: boolean) => void) => () => void;
+    };
     readonly inputPresentation?: {
         readonly scheduler?: PiTuiInputCoordinationScheduler;
         readonly onEvent?: (event: PiTuiInputDiagnosticsEvent) => void;
@@ -73,6 +78,9 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         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?: () => Promise<PiShellClipboardContent | null>;
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
@@ -83,6 +91,9 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     setMermaidRenderingMode(mode: "off" | "final" | "streaming"): void;
     setImagePresentation(showImages: boolean, imageWidthCells: number): void;
     preparePromptSubmission(text: string): PreparedPrompt;
+    canPreparePromptSuggestion(): boolean;
+    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

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

@@ -1,4 +1,4 @@
-import { backgroundSgrSpan, composeSubmittedPromptRows, displayWidth, formatSubmittedPromptTime, heldNativeHyperlinkStyle, hyperlinkSgrSpan, nativeHyperlinkStyle, overlaySpan, progressStatusText, submittedPromptLayout, stripAnsi, } from "../../../ui/components/index.js";
+import { PROMPT_GLYPH, backgroundSgrSpan, caretCell, composeSubmittedPromptRows, displayWidth, faint, formatSubmittedPromptTime, heldNativeHyperlinkStyle, hyperlinkSgrSpan, nativeHyperlinkStyle, overlaySpan, progressStatusText, submittedPromptLayout, stripAnsi, } 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, createPiShellCollapsedChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, onPiThemeChange, piShellVisibleWidth, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../components/index.js";
 import { PiTuiRuntimeAdapter, classifyPiTuiInput, } from "../tui-runtime/index.js";
@@ -29,6 +29,7 @@ export class OwnedUiSessionShellRoot {
     #viewportController;
     #viewportTheme;
     #onViewportFrame;
+    #onInputSurfaceChanged;
     #componentRuntime;
     #toolsExpanded = false;
     #thinkingVisible = true;
@@ -73,6 +74,7 @@ export class OwnedUiSessionShellRoot {
         this.#imageAssets = imageAssets;
         this.#componentRuntime = handlers;
         this.#onViewportFrame = handlers.onViewportFrame;
+        this.#onInputSurfaceChanged = handlers.onInputSurfaceChanged;
         this.#dockInputReuseEnabled = handlers.enableDockInputReuse ?? true;
         this.header = createPiShellHeader(startup);
         this.resources = createPiShellLoadedResources(startup.resources ?? [], startup.expanded ?? false);
@@ -107,6 +109,15 @@ export class OwnedUiSessionShellRoot {
             cwd,
             ...(agentDir === undefined ? {} : { agentDir }),
             onToolsExpand: () => this.#setToolsExpanded(!this.#toolsExpanded),
+            ...(this.#customViewport ? {
+                promptPresentation: {
+                    prefix: PROMPT_GLYPH,
+                    styleSuggestion: faint,
+                    styleSuggestionCaret: caretCell,
+                },
+            } : {}),
+            ...(handlers.onEditorChange === undefined ? {} : { onChange: handlers.onEditorChange }),
+            ...(handlers.onPromptSuggestionAccepted === undefined ? {} : { onPromptSuggestionAccepted: handlers.onPromptSuggestionAccepted }),
         });
         this.#viewportController = new SessionViewportController({
             enabled: this.#customViewport,
@@ -183,6 +194,20 @@ export class OwnedUiSessionShellRoot {
     preparePromptSubmission(text) {
         return this.#promptChips.prepareSubmission(text);
     }
+    canPreparePromptSuggestion() {
+        return this.usesDefaultInputSurface()
+            && this.#view.dialog === null
+            && this.#view.overlay === null
+            && this.editor.getText().length === 0;
+    }
+    canPresentPromptSuggestion() {
+        return this.canPreparePromptSuggestion()
+            && this.#view.lifecycle === "ready"
+            && this.editor.canPresentPromptSuggestion();
+    }
+    setPromptSuggestion(text) {
+        this.editor.setPromptSuggestion(text);
+    }
     update(view) {
         if (view.diagnostics.length !== this.#view.diagnostics.length
             || view.diagnostics.some((diagnostic, index) => diagnostic.sequence !== this.#view.diagnostics[index]?.sequence)) {
@@ -769,6 +794,7 @@ export class OwnedUiSessionShellRoot {
             this.#inputSurface.dispose?.();
         this.#inputSurface = next;
         this.#inputSurfaceCoordination = nextCoordination;
+        this.#onInputSurfaceChanged?.();
         this.#inputSurface.setFocused?.(true);
         this.invalidate();
     }