@timurproko/a1 0.1.8-dev.271 → 0.1.8-dev.279

package/dist/composition/owned-ui.js

@@ -37,6 +37,11 @@ export async function composeOwnedUi(options = {}) {
         snapshot: () => viewportSettingsSnapshot(settings),
         onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
     };
+    const promptSuggestions = settings === null || !ownedSurfaces ? null : {
+        generator: adapter,
+        enabled: () => settings.value("promptSuggestions") !== false,
+        onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions") !== false)),
+    };
     const shell = new OwnedUiSessionShell({
         backend: adapter,
         cwd: adapter.cwd,
@@ -44,6 +49,7 @@ export async function composeOwnedUi(options = {}) {
         ...(routeHost === null ? {} : { routeHost }),
         ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
         ...(viewportSettings === null ? {} : { viewportSettings }),
+        ...(promptSuggestions === null ? {} : { promptSuggestions }),
     });
     const application = {
         get disposed() { return adapter.disposed; },

package/dist/contracts/owned-ui/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./prompt-suggestions.js";
 export * from "./validation.js";

package/dist/contracts/owned-ui/index.js

@@ -1,3 +1,4 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
+export * from "./prompt-suggestions.js";
 export * from "./validation.js";

package/dist/contracts/owned-ui/model.d.ts

@@ -11,6 +11,39 @@ export interface OwnedUiModelInfo {
     readonly modelId: string;
     readonly displayName: string;
 }
+export interface OwnedUiPromptSuggestionIdentity {
+    readonly sessionId: OwnedUiSessionId;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo;
+}
+export interface OwnedUiPromptSuggestionRequest {
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly signal: AbortSignal;
+}
+export interface OwnedUiPromptSuggestionResult {
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly text: string | null;
+}
+export type OwnedUiPromptSuggestionState = {
+    readonly status: "idle";
+} | {
+    readonly status: "generating";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly settled: boolean;
+} | {
+    readonly status: "prepared";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly text: string;
+} | {
+    readonly status: "available";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly text: string;
+};
+export interface OwnedUiPromptSuggestionGeneratorPort {
+    generate(request: OwnedUiPromptSuggestionRequest): Promise<OwnedUiPromptSuggestionResult>;
+}
 export type OwnedUiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 export interface OwnedUiViewportSettings {
     readonly scrollbarAppearance: "auto" | "always" | "hidden";
@@ -220,11 +253,30 @@ export type OwnedUiEvent = {
     readonly type: "assistant-message-completed";
     readonly sessionId: OwnedUiSessionId;
     readonly sequence: number;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo | null;
+    readonly assistantMessageCount: number;
+    readonly successful: boolean;
+    readonly stopReason: string | null;
+    readonly toolContinuation: boolean;
 } | {
     /** A fresh agent run has started, used by follow-mode surfaces. */
     readonly type: "agent-run-started";
     readonly sessionId: OwnedUiSessionId;
     readonly sequence: number;
+} | {
+    /** The final settlement of one run, after authoritative transcript reconciliation. */
+    readonly type: "agent-run-settled";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo | null;
+    readonly assistantMessageCount: number;
+    readonly successful: boolean;
 } | {
     readonly type: "editor-state";
     readonly sessionId: OwnedUiSessionId;

package/dist/contracts/owned-ui/prompt-suggestions.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = "[NEXT USER INPUT]\nPredict the one short response the user is most likely to type next.\nUse the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.\nReturn nothing when the next input is unclear, the previous response failed, or the user should assess or correct the result.\nDo not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.\nReturn only 2-12 words, except a natural one-word command or answer is allowed.";
+/** Converts untrusted model output into one inert, bounded user-voice candidate. */
+export declare function normalizePromptSuggestionCandidate(candidate: string | null | undefined): string | null;

package/dist/contracts/owned-ui/prompt-suggestions.js

@@ -0,0 +1,41 @@
+export const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = `[NEXT USER INPUT]
+Predict the one short response the user is most likely to type next.
+Use the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.
+Return nothing when the next input is unclear, the previous response failed, or the user should assess or correct the result.
+Do not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.
+Return only 2-12 words, except a natural one-word command or answer is allowed.`;
+const ALLOWED_SINGLE_WORDS = new Set([
+    "yes", "yeah", "yep", "sure", "ok", "okay", "no",
+    "continue", "apply", "commit", "push", "deploy", "test", "check", "stop", "exit", "quit",
+]);
+/** Converts untrusted model output into one inert, bounded user-voice candidate. */
+export function normalizePromptSuggestionCandidate(candidate) {
+    if (typeof candidate !== "string")
+        return null;
+    const suggestion = candidate.trim();
+    if (suggestion.length === 0 || [...suggestion].length >= 100)
+        return null;
+    if (/[\p{C}\r\n\t]/u.test(suggestion))
+        return null;
+    if (/[\*`#]|__|~~/.test(suggestion))
+        return null;
+    if (/[.!?]\s+\S/u.test(suggestion))
+        return null;
+    const lower = suggestion.toLowerCase();
+    if (/^(api error:|prompt is too long|request timed out|invalid api key|image was too large)/.test(lower))
+        return null;
+    if (lower === "done" || /^(nothing to suggest|no suggestion|stay silent|silence\b)/.test(lower))
+        return null;
+    if (/^\w+:\s/u.test(suggestion))
+        return null;
+    if (/^(let me|i(?:'|’)ll|i(?:'|’)ve|i(?:'|’)m|i can|i would|i think|here(?:'|’)s|here is|here are|you can|you should|you could|sure,|of course|certainly)\b/i.test(suggestion))
+        return null;
+    if (/\b(thanks|thank you|looks good|sounds good|that works|that worked|nice|great|perfect|awesome|excellent)\b/i.test(suggestion))
+        return null;
+    const words = suggestion.split(/\s+/u);
+    if (words.length > 12)
+        return null;
+    if (words.length === 1 && !suggestion.startsWith("/") && !ALLOWED_SINGLE_WORDS.has(lower))
+        return null;
+    return suggestion;
+}

package/dist/contracts/owned-ui/validation.d.ts

@@ -1,6 +1,10 @@
-import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiDiagnostics, type OwnedUiEditorState, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot, type OwnedUiStatusView, type OwnedUiTerminalSurface, type OwnedUiTranscriptBlock } from "./model.js";
+import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiDiagnostics, type OwnedUiEditorState, type OwnedUiEvent, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionRequest, type OwnedUiPromptSuggestionResult, type OwnedUiPromptSuggestionState, type OwnedUiSessionViewModel, type OwnedUiSnapshot, type OwnedUiStatusView, type OwnedUiTerminalSurface, type OwnedUiTranscriptBlock } from "./model.js";
 export declare function assertOwnedUiCommand(command: OwnedUiCommand): void;
 export declare function assertOwnedUiEvent(event: OwnedUiEvent): void;
+export declare function assertOwnedUiPromptSuggestionIdentity(identity: OwnedUiPromptSuggestionIdentity): void;
+export declare function assertOwnedUiPromptSuggestionRequest(request: OwnedUiPromptSuggestionRequest): void;
+export declare function assertOwnedUiPromptSuggestionResult(result: OwnedUiPromptSuggestionResult): void;
+export declare function assertOwnedUiPromptSuggestionState(state: OwnedUiPromptSuggestionState): void;
 export declare function assertOwnedUiSessionViewModel(view: OwnedUiSessionViewModel): void;
 export declare function assertOwnedUiSnapshot(snapshot: OwnedUiSnapshot): void;
 export declare function assertOwnedUiCustomization(customization: OwnedUiCustomization): void;

package/dist/contracts/owned-ui/validation.js

@@ -116,8 +116,30 @@ export function assertOwnedUiEvent(event) {
             assertOwnedUiTranscriptBlock(event.block);
             return;
         case "assistant-message-completed":
+            assertNonNegativeInteger(event.sessionGeneration, "owned-UI assistant response session generation");
+            assertNonNegativeInteger(event.runSequence, "owned-UI assistant response run sequence");
+            assertNonNegativeInteger(event.responseSequence, "owned-UI assistant response sequence");
+            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI assistant response count");
+            if (event.model !== null)
+                assertOwnedUiModelInfo(event.model);
+            if (typeof event.successful !== "boolean")
+                throw new TypeError("owned-UI assistant response success state is invalid");
+            assertOptionalText(event.stopReason, "owned-UI assistant response stop reason", MAX_LABEL_LENGTH);
+            if (typeof event.toolContinuation !== "boolean")
+                throw new TypeError("owned-UI assistant response tool-continuation state is invalid");
+            return;
         case "agent-run-started":
             return;
+        case "agent-run-settled":
+            assertNonNegativeInteger(event.sessionGeneration, "owned-UI settlement session generation");
+            assertNonNegativeInteger(event.runSequence, "owned-UI settlement run sequence");
+            assertNonNegativeInteger(event.responseSequence, "owned-UI settlement response sequence");
+            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI settlement assistant message count");
+            if (event.model !== null)
+                assertOwnedUiModelInfo(event.model);
+            if (typeof event.successful !== "boolean")
+                throw new TypeError("owned-UI settlement success state is invalid");
+            return;
         case "editor-state":
             assertOwnedUiEditorState(event.editor);
             return;
@@ -153,6 +175,38 @@ export function assertOwnedUiEvent(event) {
             throw new TypeError("owned-UI event type is unknown");
     }
 }
+export function assertOwnedUiPromptSuggestionIdentity(identity) {
+    assertId(identity.sessionId, "prompt-suggestion session id");
+    assertNonNegativeInteger(identity.sessionGeneration, "prompt-suggestion session generation");
+    assertNonNegativeInteger(identity.runSequence, "prompt-suggestion run sequence");
+    assertNonNegativeInteger(identity.responseSequence, "prompt-suggestion response sequence");
+    assertOwnedUiModelInfo(identity.model);
+}
+export function assertOwnedUiPromptSuggestionRequest(request) {
+    assertOwnedUiPromptSuggestionIdentity(request.identity);
+    if (typeof request.signal !== "object" || request.signal === null
+        || typeof request.signal.aborted !== "boolean"
+        || typeof request.signal.addEventListener !== "function") {
+        throw new TypeError("prompt-suggestion abort signal is invalid");
+    }
+}
+export function assertOwnedUiPromptSuggestionResult(result) {
+    assertOwnedUiPromptSuggestionIdentity(result.identity);
+    assertPromptSuggestionText(result.text, true);
+}
+export function assertOwnedUiPromptSuggestionState(state) {
+    if (state.status === "idle")
+        return;
+    if (state.status !== "generating" && state.status !== "prepared" && state.status !== "available") {
+        throw new TypeError("prompt-suggestion state is invalid");
+    }
+    assertOwnedUiPromptSuggestionIdentity(state.identity);
+    if (state.status === "generating" && typeof state.settled !== "boolean") {
+        throw new TypeError("prompt-suggestion settlement state is invalid");
+    }
+    if (state.status === "prepared" || state.status === "available")
+        assertPromptSuggestionText(state.text, false);
+}
 export function assertOwnedUiSessionViewModel(view) {
     if (view.contractVersion !== OWNED_UI_CONTRACT_VERSION) {
         throw new TypeError("unsupported owned-UI contract version");
@@ -164,9 +218,7 @@ export function assertOwnedUiSessionViewModel(view) {
     assertOwnedUiStatusView(view.status);
     assertOwnedUiTerminalSurface(view.terminal);
     if (view.activeModel !== null) {
-        assertId(view.activeModel.providerId, "owned-UI provider id");
-        assertId(view.activeModel.modelId, "owned-UI model id");
-        assertBoundedText(view.activeModel.displayName, "owned-UI model display name", MAX_LABEL_LENGTH);
+        assertOwnedUiModelInfo(view.activeModel);
     }
     assertEnum(view.thinkingLevel, THINKING_LEVELS, "owned-UI thinking level");
     assertCollection(view.activeCommandIds, "owned-UI active commands", MAX_ACTIVE_COMMANDS);
@@ -331,6 +383,11 @@ export function assertOwnedUiDiagnostics(diagnostic) {
     if (typeof diagnostic.recoverable !== "boolean")
         throw new TypeError("owned-UI diagnostic recoverability is invalid");
 }
+function assertOwnedUiModelInfo(model) {
+    assertId(model.providerId, "owned-UI provider id");
+    assertId(model.modelId, "owned-UI model id");
+    assertBoundedText(model.displayName, "owned-UI model display name", MAX_LABEL_LENGTH);
+}
 function assertOwnedUiDialog(dialog) {
     assertId(dialog.id, "owned-UI dialog id");
     assertBoundedText(dialog.title, "owned-UI dialog title", MAX_LABEL_LENGTH);
@@ -381,6 +438,13 @@ function assertOptionalText(value, name, maximumBytes) {
         return;
     assertBoundedText(value, name, maximumBytes);
 }
+function assertPromptSuggestionText(value, allowEmpty) {
+    if (value === null)
+        return;
+    if (typeof value !== "string" || value.includes("\0") || (!allowEmpty && value.length === 0) || [...value].length >= 100) {
+        throw new TypeError("prompt-suggestion text is invalid");
+    }
+}
 function assertCollection(value, name, maximum) {
     if (!Array.isArray(value) || value.length > maximum)
         throw new RangeError(`${name} exceeds its maximum length`);

package/dist/foundation/supervision/server.d.ts

@@ -1,7 +1,17 @@
+import { rename, rm, writeFile } from "node:fs/promises";
 import { type SupervisorSnapshot } from "../lifecycle/index.js";
 import { type MaterializedRelease } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { type ProductPaths } from "./paths.js";
+interface EndpointMetadataCommitOperations {
+    readonly platform?: NodeJS.Platform;
+    readonly write?: typeof writeFile;
+    readonly replace?: typeof rename;
+    readonly remove?: typeof rm;
+    readonly wait?: (delayMs: number) => Promise<void>;
+}
+/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
+export declare function commitEndpointMetadata(path: string, source: string, operations?: EndpointMetadataCommitOperations): Promise<void>;
 /** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export declare class SupervisorServer {
     #private;
@@ -38,3 +48,4 @@ export declare class SupervisorServer {
     close(stopAgents?: boolean): Promise<void>;
     closeForReleaseReplacement(stopAgents: boolean): Promise<void>;
 }
+export {};

package/dist/foundation/supervision/server.js

@@ -9,6 +9,36 @@ import { processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveProductPaths } from "./paths.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+const WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160];
+/** Atomically replaces endpoint metadata while tolerating bounded Windows reader sharing. */
+export async function commitEndpointMetadata(path, source, operations = {}) {
+    const temporary = `${path}.${process.pid}.tmp`;
+    const write = operations.write ?? writeFile;
+    const replace = operations.replace ?? rename;
+    const remove = operations.remove ?? rm;
+    const wait = operations.wait ?? (delayMs => new Promise(resolvePromise => setTimeout(resolvePromise, delayMs)));
+    let committed = false;
+    try {
+        await write(temporary, source, { mode: 0o600 });
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await replace(temporary, path);
+                committed = true;
+                return;
+            }
+            catch (error) {
+                const delayMs = WINDOWS_METADATA_REPLACE_RETRY_DELAYS_MS[attempt];
+                if ((operations.platform ?? platform()) !== "win32" || delayMs === undefined || !isWindowsSharingViolation(error))
+                    throw error;
+                await wait(delayMs);
+            }
+        }
+    }
+    finally {
+        if (!committed)
+            await remove(temporary, { force: true }).catch(() => undefined);
+    }
+}
 /** Owns one release-cohort endpoint and the authenticated launch instances registered through it. */
 export class SupervisorServer {
     store;
@@ -464,11 +494,10 @@ export class SupervisorServer {
                 uncertainInstanceIds: [...this.#uncertainInstances],
             },
         };
-        const temporary = `${this.paths.endpointMetadataPath}.${process.pid}.tmp`;
-        this.#metadataWrites = this.#metadataWrites.then(async () => {
-            await writeFile(temporary, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-            await rename(temporary, this.paths.endpointMetadataPath);
-        });
+        const commit = () => commitEndpointMetadata(this.paths.endpointMetadataPath, JSON.stringify(metadata, null, 2));
+        // Platform: one exhausted filesystem replacement must fail its command, but it must not
+        // poison every later ownership revision after the sharing condition has cleared.
+        this.#metadataWrites = this.#metadataWrites.then(commit, commit);
         return this.#metadataWrites;
     }
     #send(socket, message) {
@@ -492,6 +521,10 @@ function sameContainmentIdentity(left, right) {
 function isMessageType(value, type) {
     return typeof value === "object" && value !== null && "type" in value && value.type === type;
 }
+function isWindowsSharingViolation(error) {
+    return error instanceof Error && "code" in error
+        && (error.code === "EPERM" || error.code === "EACCES" || error.code === "EBUSY");
+}
 async function ensureManagedEndpointDirectory(path) {
     await mkdir(path, { recursive: true, mode: 0o700 });
     const metadata = await lstat(path);

package/dist/integrations/pi/components/owned-editor-ux.d.ts

@@ -51,5 +51,7 @@ export interface PromptSelectionUxOptions {
     readonly decorateRow: (row: string, width: number) => string;
     readonly requestRender: () => void;
     readonly getRows: () => number;
+    /** Presentation-only columns reserved before semantic editor text. */
+    readonly promptPrefixWidth?: number;
 }
 export declare function createPromptSelectionInterceptor(editor: Editor, keybindings: KeybindingsManager, options: PromptSelectionUxOptions): OwnedEditorUxInterceptor;

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

@@ -200,7 +200,9 @@ class PromptSelectionInterceptor {
         const rows = next().map(row => row.replaceAll(ATOMIC_SPACE_SENTINEL, " "));
         const maxPadding = Math.max(0, Math.floor((width - 1) / 2));
         const padding = Math.min(this.editor.getPaddingX(), maxPadding);
-        const contentWidth = Math.max(1, width - padding * 2);
+        const prefixWidth = this.options.promptPrefixWidth ?? 0;
+        const innerWidth = Math.max(1, width - prefixWidth);
+        const contentWidth = Math.max(1, innerWidth - padding * 2);
         const layoutWidth = Math.max(1, contentWidth - (padding ? 0 : 1));
         const visualLines = editorVisualLineMap(this.editor, layoutWidth)
             ?? buildVisualLineMap(editorState(this.editor).lines, layoutWidth);
@@ -226,7 +228,7 @@ class PromptSelectionInterceptor {
                 if (to <= from)
                     continue;
                 const line = editorState(this.editor).lines[visual.logicalLine] ?? "";
-                const fromColumn = padding + visibleWidth(line.slice(segmentStart, from));
+                const fromColumn = prefixWidth + padding + visibleWidth(line.slice(segmentStart, from));
                 const toColumn = fromColumn + visibleWidth(line.slice(from, to));
                 const rendered = rows[row + 1];
                 if (rendered !== undefined && toColumn > fromColumn) {
@@ -338,7 +340,7 @@ class PromptSelectionInterceptor {
             return undefined;
         const line = editorState(this.editor).lines[visual.logicalLine] ?? "";
         const segment = line.slice(visual.startCol, visual.startCol + visual.length);
-        const displayColumn = Math.max(0, column - 1 - geometry.padding);
+        const displayColumn = Math.max(0, column - 1 - geometry.padding - (this.options.promptPrefixWidth ?? 0));
         return {
             line: visual.logicalLine,
             col: visual.startCol + indexAtDisplayWidth(segment, displayColumn),

package/dist/integrations/pi/components/shell-editor-autocomplete.js

@@ -42,6 +42,12 @@ export function createPiShellEditor(options) {
     }, keybindings, {
         paddingX: PINNED_PI_LAYOUT.editorPaddingX,
         autocompleteMaxVisible: PINNED_PI_LAYOUT.autocompleteMaxVisible,
+        ...(options.keybindingProfile === "a1" && options.promptPresentation !== undefined ? {
+            promptPrefix: options.promptPresentation.prefix,
+            styleSuggestion: options.promptPresentation.styleSuggestion,
+            styleSuggestionCaret: options.promptPresentation.styleSuggestionCaret,
+            terminalRows: options.getRows,
+        } : {}),
     });
     const editorUx = options.keybindingProfile === "a1"
         ? new OwnedEditorUxInterception([
@@ -55,6 +61,7 @@ export function createPiShellEditor(options) {
                 decorateRow: options.decorateEditorRow ?? (row => row),
                 requestRender: options.requestRender,
                 getRows: options.getRows,
+                ...(options.promptPresentation === undefined ? {} : { promptPrefixWidth: 2 }),
             }),
         ], {
             render: width => editor.render(width),
@@ -128,6 +135,9 @@ export function createPiShellEditor(options) {
         editor.onAction("app.message.followUp", options.onFollowUp);
     if (options.onDequeue !== undefined)
         editor.onAction("app.message.dequeue", options.onDequeue);
+    if (options.onPromptSuggestionAccepted !== undefined) {
+        editor.onPromptSuggestionAccepted = options.onPromptSuggestionAccepted;
+    }
     return {
         render: width => editorUx?.render(width) ?? editor.render(width),
         activateKeybindings: () => setKeybindings(keybindings),
@@ -183,6 +193,11 @@ export function createPiShellEditor(options) {
             thinkingLevel = level;
             updateBorderColor();
         },
+        setPromptSuggestion(text) {
+            editor.setPromptSuggestion(text);
+            editor.invalidate();
+        },
+        canPresentPromptSuggestion: () => editor.canPresentPromptSuggestion(),
         hasSelection: () => editorUx?.hasSelection() ?? false,
         ownsPointer: () => editorUx?.ownsPointer() ?? false,
         handlePointer: event => editorUx?.handlePointer(event) ?? false,

package/dist/integrations/pi/components/shell-shared-facade.d.ts

@@ -41,6 +41,8 @@ export interface PiShellEditorPort extends PiShellComponentPort {
     setAutocompleteMaxVisible(maxVisible: number): void;
     addAutocompleteProvider(factory: unknown): void;
     setThinkingLevel(level: OwnedUiThinkingLevel): void;
+    setPromptSuggestion(text: string | null): void;
+    canPresentPromptSuggestion(): boolean;
     hasSelection(): boolean;
     ownsPointer(): boolean;
     handlePointer(event: PiShellEditorPointerEvent): boolean;
@@ -131,6 +133,7 @@ export interface PiShellEditorOptions {
     readonly onMessageCopy?: (() => void) | undefined;
     readonly onFollowUp?: (() => void) | undefined;
     readonly onDequeue?: (() => void) | undefined;
+    readonly onPromptSuggestionAccepted?: (text: string) => void;
     readonly onCopyText?: (text: string) => void;
     readonly readClipboardContent?: () => Promise<PiShellClipboardContent | null>;
     readonly transformPastedContent?: (content: PiShellClipboardContent) => string;
@@ -141,6 +144,11 @@ export interface PiShellEditorOptions {
     readonly cwd?: string;
     readonly agentDir?: string;
     readonly autocompleteCommands?: readonly PiShellAutocompleteCommand[];
+    readonly promptPresentation?: {
+        readonly prefix: string;
+        readonly styleSuggestion: (text: string) => string;
+        readonly styleSuggestionCaret: (text: string) => string;
+    };
 }
 export interface PiShellSelectorOption {
     readonly id: string;

package/dist/integrations/pi/components/upstream/components/owned-editor.d.ts

@@ -1,18 +1,31 @@
 /**
  * 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, type EditorOptions, type EditorTheme, type TUI } from "#pi-tui";
 import type { AppKeybinding, KeybindingsManager } from "../adjacent/core/keybindings.js";
+export interface OwnedEditorOptions extends EditorOptions {
+    readonly promptPrefix?: string;
+    readonly styleSuggestion?: (text: string) => string;
+    readonly styleSuggestionCaret?: (text: string) => string;
+    readonly terminalRows?: () => number;
+}
 export declare class OwnedEditor extends Editor {
+    #private;
     private readonly keybindings;
     readonly actionHandlers: Map<keyof import("../adjacent/core/keybindings.js").AppKeybindings, () => void>;
     onEscape?: () => void;
     onCtrlD?: () => void;
     onPasteImage?: () => void;
     onExtensionShortcut?: (data: string) => boolean;
-    constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, options?: EditorOptions);
+    onPromptSuggestionAccepted?: (text: string) => void;
+    constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, options?: OwnedEditorOptions);
+    setPromptSuggestion(text: string | null): void;
+    canPresentPromptSuggestion(): boolean;
+    setText(text: string): void;
+    render(width: number): string[];
     onAction(action: AppKeybinding, handler: () => void): void;
     handleInput(data: string): void;
 }

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}`;
+        });
+    }
 }