pi-prompt-suggestions 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## Unreleased
+
+- Loads the suggestion system prompt from `prompts/suggestion-system-prompt.md`.
+- Adds global/project config files for `enabled`, `acceptTab`, `display`, `model`, `maxTokens`, and `maxChars`.
+- Supports Enter on an empty editor to submit the visible suggestion immediately.
+- Adds `display` config with default `ghost` mode and `belowEditor` fallback.
+- Adds opt-in `acceptTab` config for accepting visible suggestions with Tab.
+- Removes test-only startup suggestion and command from packaged extension code.
+- Adds stricter output filtering for meta text, labels, error text, markdown formatting, word count, assistant voice, and evaluative replies.
+- Adds README disclaimer.
+
+## 0.1.1 - 2026-05-23
+
+- Moved the suggestion system prompt into a packaged markdown file.
+
+## 0.1.0 - 2026-05-23
+
+Initial release.
+
+- Suggests short next prompts after agent responses.
+- Displays suggestions below the editor.
+- Accepts suggestions with Right Arrow when the editor is empty.
+- Preserves Tab/autocomplete behavior.
+- Includes a local `test/` harness and automated helper tests.

package/README.md

@@ -0,0 +1,90 @@
+# pi-prompt-suggestions
+
+Pi extension that suggests a natural next prompt after an agent response.
+
+Disclaimer: this is clanker slop.
+
+Behavior:
+
+- Generate a short next-prompt suggestion after `agent_end`.
+- Show it as ghost text in the input editor by default.
+- Optionally show it below the input editor.
+- Accept it with Right Arrow when the editor is empty.
+- Submit it immediately with Enter when the editor is empty.
+- Optionally accept it with Tab when the editor is empty.
+- Leave Tab/autocomplete behavior unchanged unless `acceptTab` is enabled.
+- Reject common bad model outputs such as questions, meta text, labels, errors, markdown formatting, evaluative replies, and overlong suggestions.
+
+## Install
+
+From GitHub:
+
+```bash
+pi install git:github.com/SteelDynamite/pi-prompt-suggestions@master
+```
+
+Latest release tag currently points to the older below-editor implementation:
+
+```bash
+pi install git:github.com/SteelDynamite/pi-prompt-suggestions@v0.1.1
+```
+
+After npm publishing:
+
+```bash
+pi install npm:pi-prompt-suggestions@0.1.1
+```
+
+## Configuration
+
+By default, suggestions use the active Pi model.
+
+Optional global config:
+
+```text
+~/.pi/agent/extensions/prompt-suggestions.json
+```
+
+Optional project config:
+
+```text
+.pi/prompt-suggestions.json
+```
+
+Project config overrides global config.
+
+```json
+{
+  "enabled": true,
+  "acceptTab": false,
+  "display": "ghost",
+  "model": "openai/gpt-5-mini",
+  "maxTokens": 256,
+  "maxChars": 80
+}
+```
+
+`acceptTab` defaults to `false`. When `true`, Tab accepts the visible suggestion into an empty editor without submitting; this can steal Tab from autocomplete while a suggestion is visible.
+
+`display` can be `ghost` or `belowEditor`; default is `ghost`.
+
+`model` uses `provider/modelId`. If omitted or invalid, the extension falls back to the active Pi model.
+
+The suggestion-generation system prompt lives in [`prompts/suggestion-system-prompt.md`](prompts/suggestion-system-prompt.md). Edit that file if you want to change the generation instructions before packaging/installing from source.
+
+See [`docs/plan.md`](docs/plan.md) for the implementation plan.
+
+## Development
+
+Run the validation suite:
+
+```bash
+npm run validate
+```
+
+Try the extension interactively from the local test project:
+
+```bash
+cd test
+pi
+```

package/docs/plan.md

@@ -0,0 +1,404 @@
+# Pi Next-Prompt Suggestions Extension Plan
+
+## Goal
+
+Add Claude Code-like suggested next prompts to pi as an extension, without changing pi core.
+
+The extension will:
+
+- Generate a short suggested next user prompt after an agent loop finishes.
+- Display the suggestion as inline ghost text by default, with a below-editor fallback mode.
+- Accept the suggestion with Right Arrow when the input editor is empty.
+- Submit the suggestion with Enter when the input editor is empty.
+- Optionally accept the suggestion with Tab when enabled.
+- Avoid interfering with existing Tab/autocomplete behavior by default.
+
+## UX
+
+When pi finishes responding, show a dim ghost hint in the editor:
+
+```text
+run the tests
+```
+
+Fallback `belowEditor` mode shows:
+
+```text
+→ run the tests
+```
+
+Behavior:
+
+- Press `Right Arrow` on an empty input to fill the editor with the suggestion without submitting.
+- Press `Enter` on an empty input to submit the suggestion immediately.
+- If `acceptTab` is enabled, press `Tab` on an empty input to fill the editor without submitting.
+- Start typing anything else to clear the suggestion.
+- Submit normally with Enter after accepting/editing.
+- No suggestion is shown if the next step is not obvious.
+
+## Architecture
+
+### Extension responsibilities
+
+1. Subscribe to `agent_end`.
+2. Generate a suggestion asynchronously.
+3. Render the suggestion as editor ghost text, or using `ctx.ui.setWidget()` in fallback mode.
+4. Replace the editor with a small `CustomEditor` subclass via `ctx.ui.setEditorComponent()`.
+5. Accept the suggestion on Right Arrow only when the editor is empty.
+6. Submit the suggestion on Enter only when the editor is empty.
+7. Optionally accept the suggestion on Tab only when the editor is empty and `acceptTab` is enabled.
+8. Clear stale suggestions on user input, new agent turns, session changes, and reload/shutdown.
+
+### Pi core responsibilities
+
+No required core changes.
+
+Optional future core improvement:
+
+- Add native editor suggestion primitives:
+  - `ctx.ui.setEditorSuggestion(text | undefined)`
+  - render inline ghost text
+  - accept with Tab/Right Arrow
+
+## Files
+
+Current package layout:
+
+```text
+src/index.ts                         # extension implementation
+prompts/suggestion-system-prompt.md  # model instruction prompt
+README.md                            # user docs
+docs/plan.md                         # implementation notes
+tests/*.test.ts                      # automated helper tests
+test/.pi/extensions/*.ts             # local interactive test harness
+```
+
+Installed package entrypoint is declared in `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```
+
+## Implementation Steps
+
+### 1. Create extension state
+
+Maintain module-level/session-level state:
+
+```ts
+let suggestion: string | undefined;
+let generationId = 0;
+let lastCtx: ExtensionContext | undefined;
+```
+
+State rules:
+
+- `suggestion` holds the currently visible suggestion.
+- `generationId` invalidates stale async model responses.
+- `lastCtx` lets the custom editor accept/clear via current UI context.
+
+### 2. Render suggestion
+
+Default `ghost` mode renders inside the custom editor by modifying the editor render output. This is intentionally hacky and may need adjustment if Pi editor rendering changes.
+
+Fallback `belowEditor` mode uses a widget below the editor:
+
+```ts
+ctx.ui.setWidget(
+  "next-prompt-suggestion",
+  suggestion
+    ? (_tui, theme) => ({
+        render: () => [theme.fg("dim", `→ ${suggestion}`)],
+        invalidate: () => {},
+      })
+    : undefined,
+  { placement: "belowEditor" }
+);
+```
+
+Clear with:
+
+```ts
+ctx.ui.setWidget("next-prompt-suggestion", undefined);
+```
+
+### 3. Add custom editor wrapper
+
+Subclass pi's `CustomEditor`:
+
+```ts
+class SuggestionEditor extends CustomEditor {
+  handleInput(data: string): void {
+    if (this.getText().length === 0 && suggestion) {
+      if (isRightArrow(data)) {
+        this.setText(suggestion);
+        clearSuggestion();
+        return;
+      }
+
+      if (isEnter(data)) {
+        this.setText(suggestion);
+        clearSuggestion();
+        super.handleInput(data);
+        return;
+      }
+    }
+
+    if (suggestion && isUserEditKey(data)) {
+      clearSuggestion();
+    }
+
+    super.handleInput(data);
+  }
+}
+```
+
+Important constraints:
+
+- Do not use `registerShortcut("right")`; it would consume Right Arrow globally and break cursor movement.
+- Only intercept Right Arrow/Enter when the editor is empty and a suggestion exists.
+- Right Arrow fills the editor without submitting.
+- Enter fills the editor and passes through to normal submit handling.
+- Otherwise pass through to `super.handleInput(data)`.
+
+### 4. Install editor on `session_start`
+
+```ts
+pi.on("session_start", (_event, ctx) => {
+  lastCtx = ctx;
+  ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+    new SuggestionEditor(tui, theme, keybindings)
+  );
+});
+```
+
+### 5. Generate suggestions on `agent_end`
+
+On `agent_end`:
+
+1. Clear existing suggestion.
+2. Skip if no UI.
+3. Skip if there are queued messages.
+4. Skip if editor is non-empty.
+5. Start async generation.
+6. Ignore stale response if `generationId` changed.
+7. Validate/sanitize output.
+8. Render widget.
+
+Pseudo-code:
+
+```ts
+pi.on("agent_end", async (event, ctx) => {
+  clearSuggestion();
+
+  if (!ctx.hasUI) return;
+  if (ctx.hasPendingMessages()) return;
+  if (ctx.ui.getEditorText().trim()) return;
+  if (!ctx.model) return;
+
+  const id = ++generationId;
+  const text = await generateSuggestion(event.messages, ctx);
+  if (id !== generationId) return;
+
+  const clean = sanitizeSuggestion(text);
+  if (!clean) return;
+
+  suggestion = clean;
+  renderSuggestion(ctx);
+});
+```
+
+### 6. Suggestion prompt
+
+Use the strict prompt in `prompts/suggestion-system-prompt.md`, modeled after Claude Code's observed behavior:
+
+```text
+[SUGGESTION MODE: Suggest what the user might naturally type next into pi.]
+
+First, look at the user's recent messages, original request, and the assistant's latest response.
+Predict what the user would naturally type next, not what you think they should do.
+
+The test: would the user think "I was just about to type that"?
+
+Good suggestions:
+- are 2-12 words
+- match the user's style
+- are specific
+- continue an obvious workflow
+
+Examples:
+- User asked to fix a bug and tests were not run: run the tests
+- Code was written and obvious manual check remains: try it out
+- Assistant asks whether to continue: yes
+- Task complete and changes are ready: commit this
+
+Never suggest:
+- thanks / looks good / evaluative replies
+- questions
+- Claude/pi voice like "let me" or "I'll"
+- new ideas the user did not ask about
+- multiple sentences
+- unsafe or sensitive actions, including security incidents, credentials, harm, or private data
+
+If the user explicitly said what they will ask next, suggest that exact next request.
+If a file was created/edited and tests/checks were not run, the next step is clear: suggest running the relevant test/check.
+Only reply with nothing when there is genuinely no plausible next user prompt.
+Reply with only the suggestion text.
+```
+
+### 7. Model call
+
+Use `completeSimple()` from `@earendil-works/pi-ai`.
+
+Inputs:
+
+- Current model: `ctx.model`
+- API key/headers from `ctx.modelRegistry.getApiKeyAndHeaders(ctx.model)`
+- Short context derived from recent `event.messages`
+- Small bounded max token limit; current implementation uses 256 so reasoning models have room to emit visible text
+- Do not pass `temperature`; some Pi providers/models reject it
+
+Model selection:
+
+- Use the active Pi model by default.
+- Optionally use config `model` as `provider/modelId` for a cheaper/faster suggestion model.
+- If the configured model is missing or invalid, fall back to the active Pi model.
+
+### 8. Sanitize output
+
+Reject suggestions that are likely bad:
+
+- empty
+- more than `maxChars` characters, default 80
+- more than 12 words
+- fewer than 2 words unless the single word is an allowed command/confirmation like `yes`, `continue`, `commit`, or `/help`
+- more than one sentence
+- contains newline
+- contains markdown formatting such as bullets or `**`
+- starts with labels like `Suggestion:` or `User:`
+- wraps meta text like `[no suggestion]` or `(silence)`
+- is model meta-output like `no suggestion`, `nothing to suggest`, `silence`, or `stay silent`
+- is provider/error text like `api error:`, `prompt is too long`, `request timed out`, or `invalid api key`
+- starts with assistant voice:
+  - `let me`
+  - `I'll`
+  - `I can`
+  - `Here's`
+- ends with `?`
+- is gratitude/evaluation:
+  - `thanks`
+  - `thank you`
+  - `looks good`
+  - `great`
+  - `perfect`
+
+Normalize:
+
+- trim whitespace
+- strip wrapping quotes
+- strip trailing period if otherwise valid
+
+### 9. Clear suggestion events
+
+Clear suggestion on:
+
+- `agent_start`
+- `input`
+- `session_shutdown`
+- `session_start`
+- user typing/editing in the custom editor
+- accepting the suggestion
+- `/reload` indirectly through session lifecycle
+
+### 10. Error handling
+
+If suggestion generation fails:
+
+- Do not show an error by default.
+- Optionally log/debug only.
+- Never block agent completion or user input.
+
+### 11. Configuration
+
+Supported options:
+
+```ts
+const config = {
+  enabled: true,
+  acceptTab: false,
+  display: "ghost",
+  maxChars: 80,
+  maxTokens: 256,
+  model: undefined,
+};
+```
+
+The current implementation loads extension-specific config from:
+
+```text
+~/.pi/agent/extensions/prompt-suggestions.json
+.pi/prompt-suggestions.json
+```
+
+Project config overrides global config:
+
+```json
+{
+  "enabled": true,
+  "acceptTab": false,
+  "display": "ghost",
+  "model": "openai/gpt-5-mini",
+  "maxTokens": 256,
+  "maxChars": 80
+}
+```
+
+Possible future additions:
+
+- extension flags for one-off overrides
+- `/next-suggestion on|off`
+
+## Risks
+
+1. **Right Arrow detection**
+   - Use pi-tui `matchesKey(data, "right")` rather than raw escape sequences.
+
+2. **Editor compatibility**
+   - Extend `CustomEditor`, not base `Editor`, so app-level keybindings still work.
+
+3. **Stale async result**
+   - Use `generationId` and clear on new input/agent start.
+
+4. **Suggestion quality**
+   - Prompt must strongly prefer silence over weak suggestions.
+   - Sanitizer should reject questionable output.
+
+5. **Latency/cost**
+   - Run after agent end, asynchronously.
+   - Use low max tokens.
+   - Consider cheaper model later.
+
+## Acceptance Criteria
+
+- After a successful obvious task, a short suggestion appears as ghost text, or below the editor when `display` is `belowEditor`.
+- Pressing Right Arrow on an empty editor fills the suggestion.
+- Pressing Enter on an empty editor submits the suggestion.
+- Pressing Right Arrow or Enter with non-empty editor behaves normally.
+- Typing clears the suggestion.
+- Tab/autocomplete behavior is unchanged unless `acceptTab` is enabled.
+- No suggestion appears for unclear next steps.
+- Suggestion generation failure is silent and non-blocking.
+
+## Future Improvements
+
+1. Native inline ghost text if pi core adds editor suggestion primitives.
+2. User command to enable/disable suggestions.
+3. Heuristic suggestions without model call for common cases:
+   - tests not run
+   - git changes present
+   - assistant asked yes/no
+4. Per-project style learning from prompt history.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-prompt-suggestions",
+  "version": "0.1.2",
+  "description": "Pi extension that suggests a natural next prompt after an agent response.",
+  "type": "module",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "prompt-suggestions"
+  ],
+  "homepage": "https://github.com/SteelDynamite/pi-prompt-suggestions#readme",
+  "bugs": {
+    "url": "https://github.com/SteelDynamite/pi-prompt-suggestions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SteelDynamite/pi-prompt-suggestions.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "docs",
+    "prompts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "validate": "npm run typecheck && npm test && npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.75.5",
+    "@earendil-works/pi-coding-agent": "^0.75.5",
+    "@earendil-works/pi-tui": "^0.75.5",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/prompts/suggestion-system-prompt.md

@@ -0,0 +1,34 @@
+[SUGGESTION MODE: Suggest what the user might naturally type next into pi.]
+
+First, look at the user's recent messages, original request, and the assistant's latest response.
+Predict what the user would naturally type next, not what you think they should do.
+
+The test: would the user think "I was just about to type that"?
+
+Good suggestions:
+- are 2-12 words
+- match the user's style
+- are specific
+- continue an obvious workflow
+- are imperative user prompts like "run the tests" or "commit this"
+- follow an explicit user-stated next request
+
+Examples:
+- User asked to fix a bug and tests were not run: run the tests
+- User asked to create or edit package.json with a test script and tests were not run: run the tests
+- User said "count to 10 and then I will ask you to count to 20" and assistant counted to 10: count to 20
+- Code was written and obvious manual check remains: try it out
+- Assistant asks whether to continue: yes
+- Task complete and changes are ready: commit this
+
+Never suggest:
+- thanks / looks good / evaluative replies
+- questions
+- new ideas the user did not ask about
+- multiple sentences
+- unsafe or sensitive actions, including security incidents, credentials, harm, or private data
+
+If the user explicitly said what they will ask next, suggest that exact next request.
+If a file was created/edited and tests/checks were not run, the next step is clear: suggest running the relevant test/check.
+Only reply with nothing when there is genuinely no plausible next user prompt.
+Reply with only the suggestion text.

package/src/index.ts

@@ -0,0 +1,504 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	CustomEditor,
+	convertToLlm,
+	getAgentDir,
+	type AgentEndEvent,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { completeSimple, type AssistantMessage, type Message, type Model } from "@earendil-works/pi-ai";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+const WIDGET_KEY = "next-prompt-suggestion";
+const DEFAULT_MAX_CHARS = 80;
+const DEFAULT_MAX_TOKENS = 256;
+const GLOBAL_CONFIG_RELATIVE_PATH = ["extensions", "prompt-suggestions.json"];
+const PROJECT_CONFIG_RELATIVE_PATH = [".pi", "prompt-suggestions.json"];
+const PROMPT_RELATIVE_PATH = ["prompts", "suggestion-system-prompt.md"];
+const GHOST_CURSOR = "\x1b[7m \x1b[0m";
+const GHOST_STYLE = "\x1b[2;90m";
+const ANSI_RESET = "\x1b[0m";
+const ALLOWED_SINGLE_WORD_SUGGESTIONS = new Set([
+	"yes",
+	"yeah",
+	"yep",
+	"yea",
+	"yup",
+	"sure",
+	"ok",
+	"okay",
+	"push",
+	"commit",
+	"deploy",
+	"stop",
+	"continue",
+	"check",
+	"exit",
+	"quit",
+	"no",
+]);
+
+type SuggestionDisplayMode = "ghost" | "belowEditor";
+
+interface PromptSuggestionsConfig {
+	enabled: boolean;
+	acceptTab: boolean;
+	display: SuggestionDisplayMode;
+	maxChars: number;
+	maxTokens: number;
+	model?: string;
+}
+
+type PromptSuggestionsConfigInput = Partial<PromptSuggestionsConfig>;
+
+let suggestion: string | undefined;
+let generationId = 0;
+let lastCtx: ExtensionContext | undefined;
+let currentConfig: PromptSuggestionsConfig = mergeConfigInputs();
+let currentEditor: SuggestionEditor | undefined;
+
+class SuggestionEditor extends CustomEditor {
+	requestRender(): void {
+		this.tui.requestRender(true);
+	}
+
+	render(width: number): string[] {
+		const lines = super.render(width);
+		if (currentConfig.display !== "ghost" || !suggestion || this.getText().length > 0) return lines;
+		return renderGhostSuggestionLines(lines, width, suggestion);
+	}
+
+	handleInput(data: string): void {
+		if (this.getText().length === 0 && suggestion) {
+			if (matchesKey(data, Key.right) || (currentConfig.acceptTab && matchesKey(data, Key.tab))) {
+				this.setText(suggestion);
+				clearSuggestion();
+				return;
+			}
+
+			if (matchesKey(data, Key.enter)) {
+				this.setText(suggestion);
+				clearSuggestion();
+				super.handleInput(data);
+				return;
+			}
+		}
+
+		if (suggestion && isUserEditKey(data)) {
+			clearSuggestion();
+		}
+
+		super.handleInput(data);
+	}
+}
+
+export default function promptSuggestions(pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		lastCtx = ctx;
+		currentConfig = loadConfig(ctx.cwd, (message) => debug(ctx, message));
+		clearSuggestion(ctx);
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			currentEditor = new SuggestionEditor(tui, theme, keybindings);
+			return currentEditor;
+		});
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		lastCtx = ctx;
+		clearSuggestion(ctx);
+	});
+
+	pi.on("input", (_event, ctx) => {
+		lastCtx = ctx;
+		clearSuggestion(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		clearSuggestion(ctx);
+		ctx.ui.setEditorComponent(undefined);
+		currentEditor = undefined;
+		lastCtx = undefined;
+	});
+
+	pi.on("agent_end", async (event, ctx) => {
+		lastCtx = ctx;
+		clearSuggestion(ctx);
+
+		const config = loadConfig(ctx.cwd, (message) => debug(ctx, message));
+		if (!config.enabled) return debug(ctx, "skipped: disabled by config");
+		if (!ctx.hasUI) return;
+		if (ctx.hasPendingMessages()) return debug(ctx, "skipped: pending messages");
+		if (ctx.ui.getEditorText().trim().length > 0) return debug(ctx, "skipped: editor is not empty");
+
+		const model = resolveSuggestionModel(ctx, config.model);
+		if (!model) return debug(ctx, "skipped: no model selected");
+
+		const id = ++generationId;
+		debug(ctx, "generating...");
+
+		try {
+			const text = await generateSuggestion(event.messages, ctx, model, config);
+			debug(ctx, `raw: ${JSON.stringify(truncatePlain(text, 160))}`);
+			if (id !== generationId) return debug(ctx, "ignored: stale result");
+			if (ctx.hasPendingMessages()) return debug(ctx, "ignored: pending messages appeared");
+			if (ctx.ui.getEditorText().trim().length > 0) return debug(ctx, "ignored: editor became non-empty");
+
+			const clean = sanitizeSuggestion(text, config.maxChars);
+			if (!clean) return debug(ctx, `rejected: ${JSON.stringify(truncatePlain(text, 160))}`);
+
+			showSuggestion(clean, ctx);
+			debug(ctx, `shown: ${clean}`);
+		} catch (error) {
+			debug(ctx, `error: ${error instanceof Error ? error.message : String(error)}`);
+			// Suggestion generation is best-effort and must never interrupt normal use.
+		}
+	});
+}
+
+function clearSuggestion(ctx = lastCtx): void {
+	const hadSuggestion = suggestion !== undefined;
+	generationId++;
+	suggestion = undefined;
+	ctx?.ui.setWidget(WIDGET_KEY, undefined);
+	if (hadSuggestion && currentConfig.display === "ghost") currentEditor?.requestRender();
+}
+
+function showSuggestion(text: string, ctx = lastCtx): void {
+	clearSuggestion(ctx);
+	suggestion = text;
+	renderSuggestion(ctx);
+}
+
+function renderSuggestion(ctx = lastCtx): void {
+	if (!ctx || !suggestion) return;
+	currentConfig = loadConfig(ctx.cwd, (message) => debug(ctx, message));
+	if (currentConfig.display === "ghost") {
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		currentEditor?.requestRender();
+		return;
+	}
+	ctx.ui.setWidget(
+		WIDGET_KEY,
+		(_tui, theme) => ({
+			render: (width: number) => [truncateToWidth(theme.fg("dim", `→ ${suggestion}`), width)],
+			invalidate: () => {},
+		}),
+		{ placement: "belowEditor" },
+	);
+}
+
+function renderGhostSuggestionLines(lines: string[], width: number, text: string): string[] {
+	const contentLineIndex = lines.length >= 3 ? 1 : lines.findIndex((line) => line.includes(GHOST_CURSOR));
+	if (contentLineIndex === -1) return lines;
+
+	const available = Math.max(0, width - 1);
+	const ghost = `${GHOST_STYLE}${truncateToWidth(text, available)}${ANSI_RESET}`;
+	const rendered = GHOST_CURSOR + ghost;
+	return lines.map((line, index) =>
+		index === contentLineIndex ? rendered + " ".repeat(Math.max(0, width - visibleWidth(rendered))) : line,
+	);
+}
+
+async function generateSuggestion(
+	messages: AgentEndEvent["messages"],
+	ctx: ExtensionContext,
+	model: Model<any>,
+	config: PromptSuggestionsConfig,
+): Promise<string> {
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) {
+		debug(ctx, `auth unavailable: ${"error" in auth ? auth.error : "unknown error"}`);
+		return "";
+	}
+
+	const llmMessages = convertToLlm(messages);
+	const context = buildSuggestionContext(llmMessages);
+	debug(ctx, `context: ${JSON.stringify(truncatePlain(context, 240))}`);
+	const options = {
+		apiKey: auth.apiKey,
+		headers: auth.headers,
+		maxTokens: config.maxTokens,
+		reasoning: model.reasoning ? ("minimal" as const) : undefined,
+	};
+
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt: loadSuggestionSystemPrompt(ctx.cwd, (message) => debug(ctx, message)),
+			messages: [
+				{
+					role: "user",
+					content: context,
+					timestamp: Date.now(),
+				},
+			],
+		},
+		options,
+	);
+
+	debug(
+		ctx,
+		`response: ${response.stopReason}; ${response.content.map((part) => part.type).join(",")}; ${response.errorMessage ?? ""}`,
+	);
+	if (response.diagnostics?.length) {
+		debug(ctx, `diagnostics: ${JSON.stringify(response.diagnostics).slice(0, 500)}`);
+	}
+	return extractAssistantText(response);
+}
+
+function loadSuggestionSystemPrompt(cwd: string, onWarning?: (message: string) => void): string {
+	const packagePromptPath = join(resolvePackageRoot(cwd), ...PROMPT_RELATIVE_PATH);
+	try {
+		return readFileSync(packagePromptPath, "utf-8").trim();
+	} catch (error) {
+		onWarning?.(`prompt load failed: ${packagePromptPath}: ${error instanceof Error ? error.message : String(error)}`);
+		return FALLBACK_SUGGESTION_SYSTEM_PROMPT;
+	}
+}
+
+function resolvePackageRoot(cwd: string): string {
+	let dir = import.meta.dirname;
+	while (dir !== join(dir, "..")) {
+		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, "src", "index.ts"))) return dir;
+		dir = join(dir, "..");
+	}
+	return cwd;
+}
+
+const FALLBACK_SUGGESTION_SYSTEM_PROMPT = `[SUGGESTION MODE: Suggest what the user might naturally type next into pi.]\n\nReply with only a short natural next prompt, or nothing if unclear.`;
+
+function buildSuggestionContext(messages: Message[]): string {
+	const recent = messages.slice(-8).map(formatMessageForSuggestion).filter(Boolean);
+	return `Recent conversation from the just-finished agent turn:\n\n${recent.join("\n\n")}`;
+}
+
+function formatMessageForSuggestion(message: Message): string {
+	const role = getMessageRole(message);
+	const text = extractMessageText(message).trim();
+	if (!text) return `${role}: [no text]`;
+	return `${role}: ${truncatePlain(text, 2_000)}`;
+}
+
+function getMessageRole(message: unknown): string {
+	if (isRecord(message) && typeof message.role === "string") return message.role;
+	if (isRecord(message) && typeof message.type === "string") return message.type;
+	return "message";
+}
+
+function extractMessageText(message: unknown): string {
+	if (!isRecord(message)) return "";
+	const { content } = message;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return JSON.stringify(message);
+	return content
+		.map((part) => {
+			if (!isRecord(part) || typeof part.type !== "string") return "";
+			if (part.type === "text" && typeof part.text === "string") return part.text;
+			if (part.type === "thinking") return "";
+			if (part.type === "toolCall" && typeof part.name === "string") return `[tool call: ${part.name}]`;
+			if (part.type === "image") return "[image]";
+			return "";
+		})
+		.join("\n");
+}
+
+function extractAssistantText(message: AssistantMessage): string {
+	return message.content
+		.map((part) => (part.type === "text" ? part.text : ""))
+		.join("")
+		.trim();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function sanitizeSuggestion(text: string, maxChars = DEFAULT_MAX_CHARS): string | undefined {
+	let clean = text.trim();
+	if (!clean) return undefined;
+	if (clean.includes("\n")) return undefined;
+
+	clean = clean.replace(/^```(?:\w+)?\s*/, "").replace(/\s*```$/, "").trim();
+	clean = clean.replace(/^['"“”‘’]+|['"“”‘’]+$/g, "").trim();
+	clean = clean.replace(/\.$/, "").trim();
+
+	if (!clean) return undefined;
+	if (clean.length > maxChars) return undefined;
+	if (clean.endsWith("?")) return undefined;
+	if (/[.!?].+\S/.test(clean)) return undefined;
+	if (/[\n*]|\*\*/.test(clean)) return undefined;
+	if (/^\w+:\s/.test(clean)) return undefined;
+	if (/^\(.*\)$|^\[.*\]$/.test(clean)) return undefined;
+
+	const lower = clean.toLowerCase();
+	const wordCount = clean.split(/\s+/).length;
+	if (lower === "done") return undefined;
+	if (isMetaSuggestion(lower)) return undefined;
+	if (isErrorSuggestion(lower)) return undefined;
+	if (wordCount > 12) return undefined;
+	if (wordCount < 2 && !isAllowedSingleWordSuggestion(lower, clean)) return undefined;
+	if (/^(let me|i'll|i've|i'm|i can|i would|i think|i notice|here's|here is|here are|that's|this is|this will|you can|you should|you could|sure,|of course|certainly)\b/i.test(clean)) return undefined;
+	if (/thanks|thank you|looks good|sounds good|that works|that worked|that's all|nice|great|perfect|makes sense|awesome|excellent/i.test(clean)) return undefined;
+
+	return clean;
+}
+
+function isMetaSuggestion(lower: string): boolean {
+	return (
+		lower === "nothing found" ||
+		lower.startsWith("nothing to suggest") ||
+		lower.startsWith("no suggestion") ||
+		/\bsilence is\b|\bstay(s|ing)? silent\b/.test(lower) ||
+		/^\W*silence\W*$/.test(lower)
+	);
+}
+
+function isErrorSuggestion(lower: string): boolean {
+	return (
+		lower.startsWith("api error:") ||
+		lower.startsWith("prompt is too long") ||
+		lower.startsWith("request timed out") ||
+		lower.startsWith("invalid api key") ||
+		lower.startsWith("image was too large")
+	);
+}
+
+function isAllowedSingleWordSuggestion(lower: string, clean: string): boolean {
+	if (clean.startsWith("/")) return true;
+	return ALLOWED_SINGLE_WORD_SUGGESTIONS.has(lower);
+}
+
+function isUserEditKey(data: string): boolean {
+	if (data.length === 1 && data.charCodeAt(0) >= 32) return true;
+	return (
+		matchesKey(data, Key.backspace) ||
+		matchesKey(data, Key.delete) ||
+		matchesKey(data, Key.enter) ||
+		matchesKey(data, Key.tab)
+	);
+}
+
+function truncatePlain(text: string, max: number): string {
+	return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function loadConfig(cwd: string, onWarning?: (message: string) => void): PromptSuggestionsConfig {
+	const globalPath = join(getAgentDir(), ...GLOBAL_CONFIG_RELATIVE_PATH);
+	const projectPath = join(cwd, ...PROJECT_CONFIG_RELATIVE_PATH);
+	return mergeConfigInputs(
+		readConfigFile(globalPath, onWarning),
+		readConfigFile(projectPath, onWarning),
+	);
+}
+
+function readConfigFile(path: string, onWarning?: (message: string) => void): PromptSuggestionsConfigInput {
+	if (!existsSync(path)) return {};
+	try {
+		return parseConfigInput(JSON.parse(readFileSync(path, "utf-8")), path, onWarning);
+	} catch (error) {
+		onWarning?.(`config ignored: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return {};
+	}
+}
+
+function parseConfigInput(
+	value: unknown,
+	path = "config",
+	onWarning?: (message: string) => void,
+): PromptSuggestionsConfigInput {
+	if (!isRecord(value)) {
+		onWarning?.(`config ignored: ${path}: expected object`);
+		return {};
+	}
+
+	const config: PromptSuggestionsConfigInput = {};
+	if ("enabled" in value) {
+		if (typeof value.enabled === "boolean") config.enabled = value.enabled;
+		else onWarning?.(`config ignored: ${path}: enabled must be boolean`);
+	}
+	if ("model" in value) {
+		if (typeof value.model === "string" && value.model.trim()) config.model = value.model.trim();
+		else onWarning?.(`config ignored: ${path}: model must be non-empty string`);
+	}
+	if ("acceptTab" in value) {
+		if (typeof value.acceptTab === "boolean") config.acceptTab = value.acceptTab;
+		else onWarning?.(`config ignored: ${path}: acceptTab must be boolean`);
+	}
+	if ("display" in value) {
+		if (value.display === "ghost" || value.display === "belowEditor") config.display = value.display;
+		else onWarning?.(`config ignored: ${path}: display must be \"ghost\" or \"belowEditor\"`);
+	}
+	if ("maxChars" in value) {
+		if (isPositiveInteger(value.maxChars)) config.maxChars = value.maxChars;
+		else onWarning?.(`config ignored: ${path}: maxChars must be positive integer`);
+	}
+	if ("maxTokens" in value) {
+		if (isPositiveInteger(value.maxTokens)) config.maxTokens = value.maxTokens;
+		else onWarning?.(`config ignored: ${path}: maxTokens must be positive integer`);
+	}
+	return config;
+}
+
+function mergeConfigInputs(...configs: PromptSuggestionsConfigInput[]): PromptSuggestionsConfig {
+	return {
+		enabled: true,
+		acceptTab: false,
+		display: "ghost",
+		maxChars: DEFAULT_MAX_CHARS,
+		maxTokens: DEFAULT_MAX_TOKENS,
+		...Object.assign({}, ...configs),
+	};
+}
+
+function resolveSuggestionModel(ctx: ExtensionContext, configuredModel: string | undefined): Model<any> | undefined {
+	if (!configuredModel) return ctx.model;
+	const parsed = parseModelSpec(configuredModel);
+	if (!parsed) {
+		debug(ctx, `configured model ignored: expected provider/model, got ${configuredModel}`);
+		return ctx.model;
+	}
+	const model = ctx.modelRegistry.find(parsed.provider, parsed.model);
+	if (!model) {
+		debug(ctx, `configured model not found: ${configuredModel}`);
+		return ctx.model;
+	}
+	return model;
+}
+
+function parseModelSpec(spec: string): { provider: string; model: string } | undefined {
+	const slash = spec.indexOf("/");
+	if (slash <= 0 || slash === spec.length - 1) return undefined;
+	return { provider: spec.slice(0, slash), model: spec.slice(slash + 1) };
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function debug(ctx: ExtensionContext, message: string): void {
+	if (process.env.PI_PROMPT_SUGGESTIONS_DEBUG !== "1") return;
+	ctx.ui.setStatus("next-suggestion", `suggestion: ${message}`);
+	ctx.ui.notify(`next-suggestion: ${message}`, "info");
+	try {
+		appendFileSync(join(ctx.cwd, "next-suggestion-debug.log"), `${new Date().toISOString()} ${message}\n`);
+	} catch {
+		// Debug logging must not affect the extension.
+	}
+}
+
+export const __test__ = {
+	buildSuggestionContext,
+	extractAssistantText,
+	extractMessageText,
+	formatMessageForSuggestion,
+	getMessageRole,
+	loadSuggestionSystemPrompt,
+	mergeConfigInputs,
+	parseConfigInput,
+	parseModelSpec,
+	renderGhostSuggestionLines,
+	sanitizeSuggestion,
+	truncatePlain,
+};