A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
add subtle feature hints (#452)
kt9e54ddf6ea9c
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex 223ff79a54..f17798b174 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -5,6 +5,7 @@- Changed top-level CLI help to show concise common options and commands without loading runtime resources ([ENG-4688](https://linear.app/primeintellect/issue/ENG-4688/help-command-is-obscenely-verbose)).- Fixed completed subagents cancelling their RLM heartbeats before the first run ([ENG-4652](https://linear.app/primeintellect/issue/ENG-4652/subagent-heartbeats-dont-work)).- Changed the fullscreen follow shortcut from `Alt+Down` to `Ctrl+Shift+Down` for more reliable terminal input ([ENG-4684](https://linear.app/primeintellect/issue/ENG-4684/altdown-doesnt-work)).+- Added subtle feature hints to longer-running agent turns ([ENG-4521](https://linear.app/primeintellect/issue/ENG-4521/add-subtle-hints-for-new-prime-agent-features)).- Fixed active heartbeats not resuming after Prime Agent updates ([ENG-4657](https://linear.app/primeintellect/issue/ENG-4657/heartbeats-dont-survive-updatesdaemon-reboots)).- Fixed the Agents View reordering sessions whenever prompts or heartbeats updated their activity timestamps ([ENG-4650](https://linear.app/primeintellect/issue/ENG-4650/agents-view-shifts-session-list-constantly)).- Added parent-scoped subagent lifecycle APIs: create children with readable default or orchestrator-chosen names, recover running or completed children through `rlm.list_subagents()`, continue them through agent messaging, and close/remove them with `rlm.delete_subagent()`.diff --git a/packages/coding-agent/src/modes/interactive/components/feature-hint.ts b/packages/coding-agent/src/modes/interactive/components/feature-hint.tsnew file mode 100644index 0000000000..acbe3aa420--- /dev/null+++ b/packages/coding-agent/src/modes/interactive/components/feature-hint.ts@@ -0,0 +1,46 @@+import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";+import { theme } from "../theme/theme.js";++const LABEL = "Hint:";+const SHIMMER_RADIUS = 1;+const SHIMMER_PAUSE_FRAMES = 14;++export const FEATURE_HINT_ANIMATION_INTERVAL_MS = 160;++function renderLabelShimmer(characters: string[], frame: number): string {+ if (characters.length === 0) return "";++ const travelFrames = characters.length + SHIMMER_RADIUS * 2;+ const phase = frame % (travelFrames + SHIMMER_PAUSE_FRAMES);+ const center = phase - SHIMMER_RADIUS;+ return characters+ .map((character, index) =>+ theme.fg(Math.abs(index - center) <= SHIMMER_RADIUS ? "muted" : "thinkingText", character),+ )+ .join("");+}++export class FeatureHintComponent implements Component {+ private frame = 0;++ constructor(private readonly text: string) {}++ advance(): void {+ this.frame++;+ }++ invalidate(): void {}++ render(width: number): string[] {+ const paddingX = width > 2 ? 1 : 0;+ const availableWidth = Math.max(1, width - paddingX * 2);+ const displayText = truncateToWidth(`${LABEL} ${this.text}`, availableWidth);+ const characters = Array.from(displayText);+ const labelLength = Math.min(LABEL.length, characters.length);+ const label = renderLabelShimmer(characters.slice(0, labelLength), this.frame);+ const hint = theme.fg("muted", characters.slice(labelLength).join(""));+ const line = `${" ".repeat(paddingX)}${label}${hint}`;++ return [line + " ".repeat(Math.max(0, width - visibleWidth(line))), " ".repeat(width)];+ }+}diff --git a/packages/coding-agent/src/modes/interactive/feature-hints.ts b/packages/coding-agent/src/modes/interactive/feature-hints.tsnew file mode 100644index 0000000000..6f15fa227e--- /dev/null+++ b/packages/coding-agent/src/modes/interactive/feature-hints.ts@@ -0,0 +1,136 @@+import type { AppKeybinding } from "../../core/keybindings.js";++export interface FeatureHintContext {+ getKeybinding(action: AppKeybinding): string | undefined;+ isResidentSession: boolean;+}++interface FeatureHintDefinition {+ id: string;+ getText(context: FeatureHintContext): string | undefined;+}++export interface FeatureHint {+ id: string;+ text: string;+}++export const FEATURE_HINTS: readonly FeatureHintDefinition[] = [+ {+ id: "side-question",+ getText: () => "Use /btw <question> to ask questions without interrupting your agent.",+ },+ {+ id: "prompt-stash",+ getText: ({ getKeybinding }) => {+ const key = getKeybinding("app.prompt.stash");+ return key ? `Press ${key} to stash your prompt and restore it later.` : undefined;+ },+ },+ {+ id: "follow-up",+ getText: ({ getKeybinding }) => {+ const key = getKeybinding("app.message.followUp");+ return key ? `Press ${key} to send a message after your agent finishes.` : undefined;+ },+ },+ {+ id: "heartbeat",+ getText: () => "Use /heartbeat every 10m <instruction> to repeat a task on a schedule.",+ },+ {+ id: "subagents",+ getText: () => "Prime Agent can delegate tasks to subagents and run them in parallel.",+ },+ {+ id: "agents-view",+ getText: ({ getKeybinding, isResidentSession }) => {+ if (!isResidentSession) return undefined;+ const key = getKeybinding("app.agents.back");+ return key ? `Hit ${key} for Agents View, where you can manage all your running agents.` : undefined;+ },+ },+ {+ id: "session-rewind",+ getText: () => "Run /tree to open the session tree and return to a previous message.",+ },+ {+ id: "steering",+ getText: () => "Send a message while your agent works to steer its current task.",+ },+ {+ id: "agent-messaging",+ getText: () => "Agents can message each other to share context and coordinate their work.",+ },+ {+ id: "goal",+ getText: () => "Use /goal <objective> to keep your agent working until the goal is complete.",+ },+ {+ id: "refine",+ getText: () => "Use /refine to turn useful lessons into reusable skills, memory, and prompts.",+ },+ {+ id: "persistent-ipython",+ getText: () => "Prime Agent keeps IPython variables and helpers between turns and compactions.",+ },+ {+ id: "context-usage",+ getText: () => "Use /context to check token usage, cost, and remaining context.",+ },+ {+ id: "session-fork",+ getText: () => "Use /fork to start a new session from an earlier prompt.",+ },+ {+ id: "compaction",+ getText: () => "Use /compact <instructions> to summarize old messages and free up context.",+ },+ {+ id: "auto-compaction",+ getText: () => "Prime Agent automatically compacts long sessions before context fills up.",+ },+ {+ id: "auto-refine",+ getText: () => "Prime Agent self-improves by refining skills, memories, prompts, and subagents.",+ },+ {+ id: "background-running",+ getText: ({ isResidentSession }) =>+ isResidentSession ? "You can close the terminal while your agent keeps running in the background." : undefined,+ },+] as const;++export class FeatureHintDeck {+ private remaining: FeatureHint[] = [];+ private previousId: string | undefined;++ constructor(private readonly random: () => number = Math.random) {}++ next(context: FeatureHintContext): FeatureHint | undefined {+ if (this.remaining.length === 0) {+ this.refill(context);+ }+ const hint = this.remaining.pop();+ if (hint) {+ this.previousId = hint.id;+ }+ return hint;+ }++ private refill(context: FeatureHintContext): void {+ const hints = FEATURE_HINTS.flatMap((hint) => {+ const text = hint.getText(context);+ return text ? [{ id: hint.id, text }] : [];+ });+ for (let index = hints.length - 1; index > 0; index--) {+ const random = Math.min(0.999999999, Math.max(0, this.random()));+ const target = Math.floor(random * (index + 1));+ [hints[index], hints[target]] = [hints[target]!, hints[index]!];+ }+ if (hints.length > 1 && hints[hints.length - 1]?.id === this.previousId) {+ [hints[0], hints[hints.length - 1]] = [hints[hints.length - 1]!, hints[0]!];+ }+ this.remaining = hints;+ }+}diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.tsindex 02b35c0d9e..967a743a87 100644--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts@@ -101,6 +101,7 @@ import { type AppKeybinding, KeybindingsManager } from "../../core/keybindings.jimport {createCompactionSummaryMessage,createHeartbeatPromptMessage,+ HEARTBEAT_PROMPT_CUSTOM_TYPE,HEARTBEAT_PROMPT_PREVIEW_LABEL,} from "../../core/messages.js";import { findExactModelReferenceMatch, resolveModelScopeFromModels } from "../../core/model-resolver.js";@@ -183,6 +184,7 @@ import { type FileChangeSummary, formatTotalChangeSummary, mergeTurnFileChangesimport { ExtensionEditorComponent } from "./components/extension-editor.js";import { ExtensionInputComponent } from "./components/extension-input.js";import { ExtensionSelectorComponent } from "./components/extension-selector.js";+import { FEATURE_HINT_ANIMATION_INTERVAL_MS, FeatureHintComponent } from "./components/feature-hint.js";import { FooterComponent } from "./components/footer.js";import { HeartbeatManagerComponent } from "./components/heartbeat-manager.js";import { InjectedPromptMessageComponent, isInjectedPromptMessage } from "./components/injected-prompt-message.js";@@ -203,6 +205,7 @@ import {import { TreeSelectorComponent } from "./components/tree-selector.js";import { UserMessageComponent } from "./components/user-message.js";import { UserMessageSelectorComponent } from "./components/user-message-selector.js";+import { FeatureHintDeck } from "./feature-hints.js";import { collectMarkedImages, evictImagesToBudget, formatImageMarker, imageMarkerIds } from "./image-markers.js";import type {InteractiveModeLocalSessionHost,@@ -244,6 +247,7 @@ interface PendingToolCallRenderInput {const HEARTBEAT_LEGACY_PROMPT_MIN_TOLERANCE_MS = 15_000;const HEARTBEAT_LEGACY_PROMPT_MAX_TOLERANCE_MS = 120_000;const MODEL_CATALOG_REFRESH_TTL_MS = 60_000;+const FEATURE_HINT_DELAY_MS = 5_000;export const START_HINTS = ['Try "refactor @<filepath>"',@@ -703,6 +707,7 @@ export class InteractiveMode {private statusContainer: Container;private queuedMessagesContainer: Container;private sideQuestionContainer: Container;+ private featureHintContainer: Container;private defaultEditor: CustomEditor;private editor: EditorComponent;private readonly promptStashStore: ClientPromptStashStore | undefined;@@ -735,6 +740,13 @@ export class InteractiveMode {private workingIndicatorOptions: LoaderIndicatorOptions | undefined = undefined;private workingStartedAt: number | undefined = undefined;private workingTimer: NodeJS.Timeout | undefined = undefined;+ private readonly featureHintDeck = new FeatureHintDeck();+ private currentFeatureHint: string | undefined;+ private featureHintEligibleAt = 0;+ private featureHintTimer: NodeJS.Timeout | undefined;+ private featureHintAnimationTimer: NodeJS.Timeout | undefined;+ private featureHintComponent: FeatureHintComponent | undefined;+ private featureHintRunPending = false;private pulseTimer: NodeJS.Timeout | undefined = undefined;private pulseFrame = 0;private readonly activityTracker = new AgentActivityTracker();@@ -928,6 +940,7 @@ export class InteractiveMode {this.statusContainer = new Container();this.queuedMessagesContainer = new Container();this.sideQuestionContainer = new Container();+ this.featureHintContainer = new Container();this.childAgentDetail = new ChildAgentDetailComponent(() => this.getChildAgentPanelRows(), {ui: this.ui,});@@ -1262,12 +1275,14 @@ export class InteractiveMode {this.mainContainer.addChild(this.recapContainer);this.mainContainer.addChild(this.queuedMessagesContainer);this.mainContainer.addChild(this.sideQuestionContainer);+ this.mainContainer.addChild(this.featureHintContainer);this.mainContainer.addChild(this.editorContainer);this.mainContainer.addChild(this.childAgentSummary);this.mainContainer.addChild(this.widgetContainerBelow);this.footerSlot.addChild(this.footer);this.mainContainer.addChild(this.footerSlot);this.promptDock.addChild(this.sideQuestionContainer);+ this.promptDock.addChild(this.featureHintContainer);this.promptDock.addChild(this.editorContainer);this.promptDock.addChild(this.childAgentSummary);this.promptDock.addChild(this.footerSlot);@@ -2578,6 +2593,7 @@ export class InteractiveMode {}private resetCurrentSessionRenderState(options?: { clearPromptStash?: boolean }): void {+ this.endFeatureHintRun();this.chatContainer.clear();this.shortcutGuideContainer.clear();this.pendingMessagesContainer.clear();@@ -2921,9 +2937,11 @@ export class InteractiveMode {this.loadingAnimation = this.createWorkingLoader();this.statusContainer.addChild(this.loadingAnimation);this.startWorkingTimer();+ this.startFeatureHintPresentation();}private stopWorkingLoader(): void {+ this.clearFeatureHintPresentation();if (this.workingTimer) {clearInterval(this.workingTimer);this.workingTimer = undefined;@@ -2936,6 +2954,94 @@ export class InteractiveMode {this.statusContainer.clear();}+ private startFeatureHintPresentation(): void {+ this.clearFeatureHintPresentation();+ if (this.featureHintEligibleAt === 0) {+ this.featureHintEligibleAt = Date.now() + FEATURE_HINT_DELAY_MS;+ }+ const delay = Math.max(0, this.featureHintEligibleAt - Date.now());+ if (delay === 0) {+ this.showFeatureHint();+ return;+ }+ this.featureHintTimer = setTimeout(() => {+ this.featureHintTimer = undefined;+ this.showFeatureHint();+ }, delay);+ this.featureHintTimer.unref?.();+ }++ private showFeatureHint(): void {+ if (+ !this.loadingAnimation ||+ !this.shouldShowWorkingLoader() ||+ !this.statusContainer.children.includes(this.loadingAnimation)+ ) {+ return;+ }+ if (!this.currentFeatureHint) {+ const hint = this.featureHintDeck.next({+ getKeybinding: (action) => {+ const key = keyText(action);+ return key ? this.capitalizeKey(key) : undefined;+ },+ isResidentSession: this.options.returnToAgentsView === true,+ });+ this.currentFeatureHint = hint?.text;+ }+ if (!this.currentFeatureHint) {+ return;+ }+ this.featureHintComponent = new FeatureHintComponent(this.currentFeatureHint);+ this.featureHintContainer.addChild(this.featureHintComponent);+ this.featureHintAnimationTimer = setInterval(() => {+ this.featureHintComponent?.advance();+ this.ui.requestRender();+ }, FEATURE_HINT_ANIMATION_INTERVAL_MS);+ this.featureHintAnimationTimer.unref?.();+ this.ui.requestRender();+ }++ private clearFeatureHintPresentation(): void {+ if (this.featureHintTimer) {+ clearTimeout(this.featureHintTimer);+ this.featureHintTimer = undefined;+ }+ if (this.featureHintAnimationTimer) {+ clearInterval(this.featureHintAnimationTimer);+ this.featureHintAnimationTimer = undefined;+ }+ if (this.featureHintComponent) {+ this.featureHintContainer.removeChild(this.featureHintComponent);+ this.featureHintComponent = undefined;+ }+ }++ private endFeatureHintRun(): void {+ this.clearFeatureHintPresentation();+ this.currentFeatureHint = undefined;+ this.featureHintEligibleAt = 0;+ this.featureHintRunPending = false;+ }++ private prepareFeatureHintRun(message: AgentMessage): void {+ if (!this.featureHintRunPending) return;+ if (message.role === "assistant") {+ this.featureHintRunPending = false;+ return;+ }+ const startsNewRun =+ message.role === "user" ||+ isAgentSessionMessage(message) ||+ (message.role === "custom" && message.customType === HEARTBEAT_PROMPT_CUSTOM_TYPE);+ if (!startsNewRun) return;++ this.endFeatureHintRun();+ if (this.shouldShowWorkingLoader()) {+ this.startFeatureHintPresentation();+ }+ }+private updateWorkingPulse(): void {const active = this.isAgentStreaming() || this.countRunningChildAgents() > 0;if (!active) {@@ -4562,6 +4668,9 @@ export class InteractiveMode {this.updateConnectionStateFromEvent(event);// A new user message resets the activity tracker to 0, so the in-flight baseline must// reset with it. (agent_start on auto-retry does not reset the tracker.)+ if (event.type === "message_start") {+ this.prepareFeatureHintRun(event.message);+ }if (event.type === "message_start" && (event.message.role === "user" || isAgentSessionMessage(event.message))) {this.contextUsageTokenBaseline = 0;this.setSessionHasMessages(true);@@ -4574,6 +4683,7 @@ export class InteractiveMode {switch (event.type) {case "agent_start":+ this.featureHintRunPending = this.getRetryAttempt() === 0;this.resetPendingToolState();this.renderRecap();if (this.settingsManager.getShowTerminalProgress()) {@@ -9236,6 +9346,7 @@ ${interrupt ? `| \`${interrupt}\` | Interrupt current operation |\n` : ""}${shorthis.ui.terminal.setProgress(false);}this.stopWorkingLoader();+ this.endFeatureHintRun();this.stopWorkingPulse();this.stopGoalTrayTimer();this.closeHeartbeatManager();diff --git a/packages/coding-agent/test/interactive-mode-feature-hints.test.ts b/packages/coding-agent/test/interactive-mode-feature-hints.test.tsnew file mode 100644index 0000000000..d5d12b7877--- /dev/null+++ b/packages/coding-agent/test/interactive-mode-feature-hints.test.ts@@ -0,0 +1,230 @@+import { type Component, Container, visibleWidth } from "@earendil-works/pi-tui";+import stripAnsi from "strip-ansi";+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";+import { FEATURE_HINT_ANIMATION_INTERVAL_MS } from "../src/modes/interactive/components/feature-hint.js";+import { FEATURE_HINTS, FeatureHintDeck } from "../src/modes/interactive/feature-hints.js";+import { InteractiveMode } from "../src/modes/interactive/interactive-mode.js";+import { initTheme } from "../src/modes/interactive/theme/theme.js";++class FakeLoader implements Component {+ readonly stop = vi.fn();++ invalidate(): void {}++ render(width: number): string[] {+ return ["loader".padEnd(width)];+ }+}++function callPrivate(mode: object, name: string): void {+ Reflect.get(InteractiveMode.prototype, name).call(mode);+}++function createMode() {+ const statusContainer = new Container();+ const featureHintContainer = new Container();+ const loader = new FakeLoader();+ statusContainer.addChild(loader);+ const hint = { id: "test", text: "This is a deliberately long feature hint for narrow terminals." };+ const featureHintDeck = { next: vi.fn(() => hint) };+ const requestRender = vi.fn();+ const mode = {+ statusContainer,+ featureHintContainer,+ loadingAnimation: loader,+ workingVisible: true,+ connectionState: { isStreaming: true },+ workingTimer: undefined,+ workingStartedAt: 0,+ featureHintDeck,+ currentFeatureHint: undefined,+ featureHintEligibleAt: 0,+ featureHintTimer: undefined,+ featureHintAnimationTimer: undefined,+ featureHintComponent: undefined,+ featureHintRunPending: false,+ options: { returnToAgentsView: true },+ ui: { requestRender },+ };+ Object.setPrototypeOf(mode, InteractiveMode.prototype);+ return { mode, statusContainer, featureHintContainer, loader, featureHintDeck, requestRender };+}++describe("feature hint deck", () => {+ it("shows every available hint before repeating and avoids a boundary repeat", () => {+ const deck = new FeatureHintDeck(() => 0);+ const context = { getKeybinding: (action: string) => `Custom ${action}`, isResidentSession: true };+ const firstCycle = FEATURE_HINTS.map(() => deck.next(context));++ expect(firstCycle.every((hint) => hint !== undefined)).toBe(true);+ expect(new Set(firstCycle.map((hint) => hint?.id)).size).toBe(FEATURE_HINTS.length);+ expect(deck.next(context)?.id).not.toBe(firstCycle.at(-1)?.id);+ });++ it("uses configured shortcuts in keybinding-based hints", () => {+ const deck = new FeatureHintDeck(() => 0);+ const context = {+ getKeybinding: (action: string) => {+ if (action === "app.prompt.stash") return "Meta+S";+ if (action === "app.message.followUp") return "Meta+Enter";+ return "Meta+Left";+ },+ isResidentSession: true,+ };+ const hints = FEATURE_HINTS.map(() => deck.next(context));++ expect(hints.find((hint) => hint?.id === "prompt-stash")?.text).toContain("Meta+S");+ expect(hints.find((hint) => hint?.id === "follow-up")?.text).toContain("Meta+Enter");+ expect(hints.find((hint) => hint?.id === "agents-view")?.text).toContain("Meta+Left");+ });++ it("covers Prime Agent workflows with capability-focused copy", () => {+ const deck = new FeatureHintDeck(() => 0);+ const hints = FEATURE_HINTS.map(() => deck.next({ getKeybinding: () => "Meta+A", isResidentSession: true }));+ const textById = new Map(hints.map((hint) => [hint?.id, hint?.text]));++ expect(textById.get("subagents")).toBe("Prime Agent can delegate tasks to subagents and run them in parallel.");+ expect(textById.get("agents-view")).toContain("Agents View");+ expect(textById.get("session-rewind")).toContain("/tree");+ expect(textById.get("steering")).toContain("steer");+ expect(textById.get("agent-messaging")).toContain("message each other");+ expect(textById.get("goal")).toContain("/goal");+ expect(textById.get("refine")).toContain("/refine");+ expect(textById.get("persistent-ipython")).toContain("IPython");+ expect(textById.get("context-usage")).toContain("/context");+ expect(textById.get("session-fork")).toContain("/fork");+ expect(textById.get("compaction")).toContain("/compact");+ expect(textById.get("auto-compaction")).toContain("automatically compacts");+ expect(textById.get("auto-refine")).toContain("self-improves");+ expect(textById.get("background-running")).toContain("close the terminal");+ });++ it("keeps every hint concise", () => {+ const deck = new FeatureHintDeck(() => 0);+ const hints = FEATURE_HINTS.map(() => deck.next({ getKeybinding: () => "Ctrl+Key", isResidentSession: true }));++ expect(hints.every((hint) => hint !== undefined && hint.text.length <= 80)).toBe(true);+ });++ it("hides resident-only hints in ephemeral sessions", () => {+ const context = { getKeybinding: () => "Left", isResidentSession: false };+ const textById = new Map(FEATURE_HINTS.map((hint) => [hint.id, hint.getText(context)]));++ expect(textById.get("agents-view")).toBeUndefined();+ expect(textById.get("background-running")).toBeUndefined();+ });+});++describe("InteractiveMode feature hints", () => {+ beforeAll(() => {+ initTheme("dark");+ });++ beforeEach(() => {+ vi.useFakeTimers();+ vi.setSystemTime(0);+ });++ afterEach(() => {+ vi.useRealTimers();+ });++ it("adds one animated truncated hint above the prompt after a sustained agent run", () => {+ const { mode, statusContainer, featureHintContainer, featureHintDeck, requestRender } = createMode();++ callPrivate(mode, "startFeatureHintPresentation");+ vi.advanceTimersByTime(4_999);+ expect(statusContainer.children).toHaveLength(1);+ expect(featureHintContainer.children).toHaveLength(0);+ expect(featureHintDeck.next).not.toHaveBeenCalled();++ vi.advanceTimersByTime(1);+ expect(statusContainer.children).toHaveLength(1);+ expect(featureHintContainer.children).toHaveLength(1);+ const lines = featureHintContainer.children[0]?.render(24) ?? [];+ expect(lines).toHaveLength(2);+ expect(stripAnsi(lines[0] ?? "")).toContain("Hint:");+ expect(lines[1]?.trim()).toBe("");+ expect(visibleWidth(lines[0] ?? "")).toBeLessThanOrEqual(24);+ expect(featureHintDeck.next).toHaveBeenCalledTimes(1);+ expect(requestRender).toHaveBeenCalledTimes(1);++ vi.advanceTimersByTime(FEATURE_HINT_ANIMATION_INTERVAL_MS);+ const animatedLines = featureHintContainer.children[0]?.render(24) ?? [];+ expect(stripAnsi(animatedLines[0] ?? "")).toBe(stripAnsi(lines[0] ?? ""));+ expect(animatedLines[0]).not.toBe(lines[0]);+ expect(requestRender).toHaveBeenCalledTimes(2);+ });++ it("cancels a pending hint when the loader stops", () => {+ const { mode, statusContainer, featureHintContainer, featureHintDeck, requestRender } = createMode();++ callPrivate(mode, "startFeatureHintPresentation");+ vi.advanceTimersByTime(2_000);+ callPrivate(mode, "stopWorkingLoader");+ vi.advanceTimersByTime(5_000);++ expect(statusContainer.children).toHaveLength(0);+ expect(featureHintContainer.children).toHaveLength(0);+ expect(featureHintDeck.next).not.toHaveBeenCalled();+ expect(requestRender).not.toHaveBeenCalled();+ });++ it("retains the hint and remaining delay when the loader is recreated", () => {+ const { mode, statusContainer, featureHintContainer, featureHintDeck } = createMode();++ callPrivate(mode, "startFeatureHintPresentation");+ vi.advanceTimersByTime(3_000);+ callPrivate(mode, "stopWorkingLoader");++ const replacement = new FakeLoader();+ Reflect.set(mode, "loadingAnimation", replacement);+ statusContainer.addChild(replacement);+ callPrivate(mode, "startFeatureHintPresentation");+ vi.advanceTimersByTime(1_999);+ expect(statusContainer.children).toHaveLength(1);+ expect(featureHintContainer.children).toHaveLength(0);+ expect(featureHintDeck.next).not.toHaveBeenCalled();++ vi.advanceTimersByTime(1);+ expect(statusContainer.children).toHaveLength(1);+ expect(featureHintContainer.children).toHaveLength(1);+ expect(featureHintDeck.next).toHaveBeenCalledTimes(1);++ callPrivate(mode, "endFeatureHintRun");+ expect(statusContainer.children).toHaveLength(1);+ expect(featureHintContainer.children).toHaveLength(0);+ expect(Reflect.get(mode, "currentFeatureHint")).toBeUndefined();+ });++ it("keeps hints for steering and continuations, then restarts the delay for new runs", () => {+ const { mode } = createMode();+ Reflect.set(mode, "currentFeatureHint", "Existing hint");+ Reflect.set(mode, "featureHintEligibleAt", 5_000);++ Reflect.get(InteractiveMode.prototype, "prepareFeatureHintRun").call(mode, {+ role: "user",+ content: [{ type: "text", text: "steer" }],+ timestamp: 0,+ });+ expect(Reflect.get(mode, "currentFeatureHint")).toBe("Existing hint");++ Reflect.set(mode, "featureHintRunPending", true);+ Reflect.get(InteractiveMode.prototype, "prepareFeatureHintRun").call(mode, {+ role: "assistant",+ content: [],+ });+ expect(Reflect.get(mode, "currentFeatureHint")).toBe("Existing hint");+ expect(Reflect.get(mode, "featureHintRunPending")).toBe(false);++ Reflect.set(mode, "featureHintRunPending", true);+ Reflect.get(InteractiveMode.prototype, "prepareFeatureHintRun").call(mode, {+ role: "user",+ content: [{ type: "text", text: "new run" }],+ timestamp: 0,+ });+ expect(Reflect.get(mode, "currentFeatureHint")).toBeUndefined();+ expect(Reflect.get(mode, "featureHintEligibleAt")).toBe(5_000);+ expect(Reflect.get(mode, "featureHintTimer")).toBeDefined();+ });+});diff --git a/packages/coding-agent/test/interactive-mode-status.test.ts b/packages/coding-agent/test/interactive-mode-status.test.tsindex b6a5b6e77e..d54a3a8d06 100644--- a/packages/coding-agent/test/interactive-mode-status.test.ts+++ b/packages/coding-agent/test/interactive-mode-status.test.ts@@ -636,7 +636,9 @@ describe("InteractiveMode pending bash components", () => {expect(loader.intervalId).not.toBeNull();const editorStub = { clearHistory: vi.fn(), setText: vi.fn() };+ const endFeatureHintRun = vi.fn();const fakeThis = {+ endFeatureHintRun,chatContainer: new Container(),shortcutGuideContainer: new Container(),pendingMessagesContainer: new Container(),@@ -668,6 +670,7 @@ describe("InteractiveMode pending bash components", () => {).resetCurrentSessionRenderState.call(fakeThis);expect(loader.intervalId).toBeNull();+ expect(endFeatureHintRun).toHaveBeenCalledOnce();expect((fakeThis as unknown as { activeBashComponent: unknown }).activeBashComponent).toBeUndefined();});});diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.mdindex bb38170dc7..997b4e5cdc 100644--- a/packages/tui/CHANGELOG.md+++ b/packages/tui/CHANGELOG.md@@ -3,6 +3,8 @@## [Unreleased]- Changed the fullscreen follow shortcut from `Alt+Down` to `Ctrl+Shift+Down` for more reliable terminal input ([ENG-4684](https://linear.app/primeintellect/issue/ENG-4684/altdown-doesnt-work)).+- Fixed autocomplete popups overlapping the prompt's top edge.+## [0.3.1] - 2026-07-15- Fixed fullscreen Markdown table selections copying borders instead of tab-separated cell content ([ENG-4629](https://linear.app/primeintellect/issue/ENG-4629/respect-table-boundaries-when-selecting)).diff --git a/packages/tui/src/components/editor.ts b/packages/tui/src/components/editor.tsindex 84ccff8f3e..52a8e58243 100644--- a/packages/tui/src/components/editor.ts+++ b/packages/tui/src/components/editor.ts@@ -2463,6 +2463,7 @@ export class Editor implements Component, Focusable {this.autocompleteOverlay = this.tui.showOverlay(this.autocompleteOverlayComponent, {width: "100%",aboveMarker: this.autocompleteAnchorMarker,+ offsetY: -1,nonCapturing: true,visible: () => this.focused && this.autocompleteState !== null,});diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.tsindex 2a09f372b5..103edbb916 100644--- a/packages/tui/src/tui.ts+++ b/packages/tui/src/tui.ts@@ -18,6 +18,7 @@ import {normalizeTerminalOutput,sliceByColumn,sliceWithWidth,+ stripAnsi,visibleContentSpan,visibleWidth,} from "./utils.js";@@ -1134,7 +1135,7 @@ export class TUI extends Container {col: number;w: number;scrollback: boolean;- aboveMarker?: { line: number; col: number };+ aboveMarker?: { line: number; col: number; offsetY: number };}[] = [];let minLinesNeeded = result.length;@@ -1143,12 +1144,16 @@ export class TUI extends Container {for (const entry of visibleEntries) {const { component, options } = entry;const scrollback = options?.scrollback === true;- let aboveMarker: { line: number; col: number } | undefined;+ let aboveMarker: { line: number; col: number; offsetY: number } | undefined;if (options?.aboveMarker) {for (let line = result.length - 1; line >= 0; line--) {const markerIndex = result[line].indexOf(options.aboveMarker);if (markerIndex === -1) continue;- aboveMarker = { line, col: visibleWidth(result[line].slice(0, markerIndex)) };+ aboveMarker = {+ line,+ col: visibleWidth(result[line].slice(0, markerIndex)),+ offsetY: options.offsetY ?? 0,+ };result[line] =result[line].slice(0, markerIndex) + result[line].slice(markerIndex + options.aboveMarker.length);break;@@ -1194,8 +1199,14 @@ export class TUI extends Container {const { component, w, scrollback, aboveMarker } = renderedOverlay;let { overlayLines, row, col } = renderedOverlay;if (aboveMarker) {- const markerRow = aboveMarker.line - viewportStart;- if (markerRow <= 0 || markerRow >= termHeight) continue;+ const markerRow = Math.max(1, aboveMarker.line - viewportStart + aboveMarker.offsetY);+ if (markerRow >= termHeight) continue;+ while (overlayLines.length > markerRow && stripAnsi(overlayLines[0] ?? "").trim().length === 0) {+ overlayLines = overlayLines.slice(1);+ }+ while (overlayLines.length > markerRow && stripAnsi(overlayLines.at(-1) ?? "").trim().length === 0) {+ overlayLines = overlayLines.slice(0, -1);+ }if (overlayLines.length > markerRow) {overlayLines = overlayLines.slice(overlayLines.length - markerRow);}diff --git a/packages/tui/test/editor-autocomplete-overlay.test.ts b/packages/tui/test/editor-autocomplete-overlay.test.tsindex 81d117e73b..663eb55720 100644--- a/packages/tui/test/editor-autocomplete-overlay.test.ts+++ b/packages/tui/test/editor-autocomplete-overlay.test.ts@@ -72,8 +72,30 @@ describe("editor autocomplete overlay", () => {await terminal.waitForRender();const viewport = terminal.getViewport();- assert.ok(viewport.some((line) => line.includes("help")));+ assert.ok(viewport[0]?.includes("help"));+ assert.ok(viewport[1]?.includes("hotkeys"));assert.ok(viewport[3]?.includes("/"));tui.stop();});++ it("keeps one suggestion visible when the editor is at the terminal top edge", async () => {+ const terminal = new VirtualTerminal(40, 3);+ const tui = new TUI(terminal);+ const editor = new Editor(tui, defaultEditorTheme);+ tui.addChild(editor);+ tui.setFocus(editor);+ editor.setAutocompleteProvider(autocompleteProvider);+ tui.start();++ editor.handleInput("/");+ await Promise.resolve();+ await new Promise((resolve) => setImmediate(resolve));+ tui.requestRender(true);+ await terminal.waitForRender();++ const viewport = terminal.getViewport();+ assert.ok(viewport[0]?.includes("hotkeys"));+ assert.ok(viewport[1]?.includes("/"));+ tui.stop();+ });});diff --git a/packages/tui/test/editor.test.ts b/packages/tui/test/editor.test.tsindex 1af736c982..2251eb89e8 100644--- a/packages/tui/test/editor.test.ts+++ b/packages/tui/test/editor.test.ts@@ -2055,6 +2055,36 @@ describe("Editor component", () => {assert.equal(tui.hasOverlay(), false);});+ it("keeps the prompt top edge visible below autocomplete", async () => {+ const terminal = new VirtualTerminal(60, 12);+ const tui = new TUI(terminal);+ const editor = new Editor(tui, defaultEditorTheme);+ tui.addChild(editor);+ tui.start();+ tui.enterFullscreen({ scroll: [], dock: editor, mouse: false });+ tui.setFocus(editor);+ editor.setAutocompleteProvider({+ getSuggestions: async () => ({+ items: [+ { value: "/model", label: "model", description: "Change model" },+ { value: "/help", label: "help", description: "Show help" },+ ],+ prefix: "/",+ }),+ applyCompletion,+ });++ editor.handleInput("/");+ await flushAutocomplete();+ tui.requestRender(true);+ await new Promise<void>((resolve) => process.nextTick(resolve));+ await terminal.waitForRender();++ const viewport = terminal.getViewport();+ assert.match(viewport[9] ?? "", /^─+$/);+ tui.stop();+ });+it("auto-applies single force-file suggestion without showing menu", async () => {const editor = new Editor(createTestTUI(), defaultEditorTheme);diff --git a/packages/tui/test/overlay-options.test.ts b/packages/tui/test/overlay-options.test.tsindex 97e52f077e..1199780f08 100644--- a/packages/tui/test/overlay-options.test.ts+++ b/packages/tui/test/overlay-options.test.ts@@ -535,6 +535,39 @@ describe("TUI overlay options", () => {tui.stop();});+ it("applies vertical offsets to marker-anchored overlays", async () => {+ const terminal = new VirtualTerminal(20, 8);+ const tui = new TUI(terminal);+ const marker = "\x1b_pi:offset-overlay\x07";+ const content = new StaticOverlay([+ "transcript 1",+ "transcript 2",+ "transcript 3",+ "underlay 1",+ "prompt edge",+ `${marker}input`,+ "footer 1",+ "footer 2",+ ]);++ tui.addChild(content);+ tui.showOverlay(new StaticOverlay(["suggestion", "description"]), {+ width: "100%",+ aboveMarker: marker,+ offsetY: -1,+ nonCapturing: true,+ });+ tui.start();+ await renderAndFlush(tui, terminal);++ const viewport = terminal.getViewport();+ assert.equal(viewport[2]?.trimEnd(), "suggestion");+ assert.equal(viewport[3]?.trimEnd(), "description");+ assert.equal(viewport[4], "prompt edge");+ assert.equal(viewport[5], "input");+ tui.stop();+ });+it("anchors above fullscreen dock content", async () => {const terminal = new VirtualTerminal(20, 8);const tui = new TUI(terminal);