@ikuma.cloud/pix-mcp 0.0.7 → 0.0.8

package/README.md

@@ -266,10 +266,21 @@ the stable `/mcp-prompt` command so catalog changes do not leave stale slash
 commands behind:
 
 ```text
+/mcp-prompt
 /mcp-prompt list [server]
 /mcp-prompt run <server> <prompt> [name=value ...]
 ```
 
+In TUI mode, `/mcp-prompt` without arguments opens a native prompt selector
+that shows the focused prompt's title and description, followed by native input
+dialogs. Required and optional arguments are requested in declaration order;
+leaving an optional input empty omits it. The rendered prompt is placed in Pi's
+editor so you can review or modify it before sending. Image blocks are stored in
+private temporary files and inserted as `@` references. Escape cancels without
+retrieving the prompt. The explicit `list` and `run` forms remain available in
+every mode; `run` submits immediately and can pass an intentional empty value as
+`name=`.
+
 Arguments use shell-style quoting. Positional values map to the prompt's declared
 argument order; `name=value` selects a declared argument explicitly. Quote or escape
 an equals sign in a positional value (for example, `"a=b"` or `a\=b`) to avoid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "publishConfig": {
     "access": "public"
   },
@@ -28,11 +28,13 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.87.1",
     "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "typebox": "1.3.27"
   }
 }

package/src/catalog.ts

@@ -78,7 +78,7 @@ export function summary(item: Entry) {
 
 export function compact(value: string, limit: number): string {
   const text = value
-    .replace(/\p{Cc}/gu, " ")
+    .replace(/[\p{C}\p{Zl}\p{Zp}]/gu, " ")
     .replace(/\s+/g, " ")
     .trim();
   return text.length <= limit ? text : `${text.slice(0, limit)}…`;

package/src/index.ts

@@ -2,13 +2,19 @@ import { resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
+  ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { Prompt, Tool } from "@modelcontextprotocol/sdk/types.js";
 import { compact, entry, search, summary, type Entry } from "./catalog.ts";
 import { Connection } from "./client.ts";
 import { readConfig, type ConfigIssue, type ServerConfig } from "./config.ts";
-import { formatResult } from "./output.ts";
+import {
+  formatEditableContent,
+  formatResult,
+  removeEditablePromptGuard,
+} from "./output.ts";
+import { pickPrompt } from "./prompt-picker.ts";
 import {
   formatPromptList,
   formatPromptResult,
@@ -16,6 +22,8 @@ import {
   promptCompletions,
   promptKey,
   resolvePromptArguments,
+  type PromptArgumentToken,
+  type PromptCommand,
   type PromptEntry,
 } from "./prompts.ts";
 import { prepareSchema } from "./schema.ts";
@@ -31,6 +39,11 @@ interface Rejections {
   }[];
 }
 
+interface PromptSelection {
+  command: PromptCommand;
+  item: PromptEntry;
+}
+
 interface State {
   alive: boolean;
   status: string;
@@ -40,6 +53,8 @@ interface State {
   connections: Map<string, Connection>;
   rejected: Map<string, Rejections>;
   configIssues: ConfigIssue[];
+  promptDraftCleanups: Set<() => Promise<void>>;
+  promptDraftGuards: Set<string>;
 }
 
 const discoveryParameters = Type.Object(
@@ -73,7 +88,7 @@ export default function mcp(pi: ExtensionAPI) {
       "Read this MCP config file for this session (default: .mcp.json).",
   });
   pi.registerCommand("mcp-prompt", {
-    description: "List or run a user-selected MCP prompt",
+    description: "Select, list, or run a user-controlled MCP prompt",
     getArgumentCompletions: (prefix) =>
       promptCompletions(prefix, [...(state?.prompts.values() ?? [])]),
     async handler(input, ctx) {
@@ -81,7 +96,14 @@ export default function mcp(pi: ExtensionAPI) {
         const owner = state;
         if (!owner) throw new Error("MCP session has not started.");
         current(owner);
-        const command = parsePromptCommand(input);
+        const editBeforeSending = ctx.mode === "tui" && input.trim() === "";
+        const selection = editBeforeSending
+          ? await choosePrompt(owner, ctx)
+          : undefined;
+        const command =
+          selection?.command ??
+          (editBeforeSending ? undefined : parsePromptCommand(input));
+        if (!command) return;
         if (command.action === "list") {
           if (
             command.server &&
@@ -113,34 +135,64 @@ export default function mcp(pi: ExtensionAPI) {
           ctx.ui.notify(text, "info");
           return;
         }
-        const item = owner.prompts.get(promptKey(command.server, command.name));
+        const key = promptKey(command.server, command.name);
+        const item = selection?.item ?? owner.prompts.get(key);
         if (!item)
           throw new Error(
             "Unknown or unavailable MCP prompt. List prompts again.",
           );
+        const ensureSelectedPromptCurrent = () => {
+          if (selection && owner.prompts.get(key) !== item)
+            throw new Error(
+              "MCP prompt catalog changed. Open the picker again.",
+            );
+        };
+        ensureSelectedPromptCurrent();
         const connection = owner.connections.get(command.server);
         if (!connection) throw new Error("MCP connection unavailable.");
         const args = resolvePromptArguments(
           item.prompt,
           command.argumentTokens,
         );
-        const result = await connection.getPrompt(
-          item.prompt.name,
-          args,
-          ctx.signal,
-        );
-        current(owner);
-        const formatted = await formatPromptResult(
-          result,
-          item.server,
-          item.prompt.name,
-        );
-        current(owner);
-        ctx.signal?.throwIfAborted();
-        pi.sendUserMessage(
-          formatted.content,
-          ctx.isIdle() ? undefined : { deliverAs: "followUp" },
-        );
+        if (ctx.mode === "tui")
+          ctx.ui.setStatus(
+            "mcp-prompt",
+            `Loading ${item.server} / ${item.prompt.name}…`,
+          );
+        try {
+          const result = await connection.getPrompt(
+            item.prompt.name,
+            args,
+            ctx.signal,
+          );
+          current(owner);
+          ensureSelectedPromptCurrent();
+          const formatted = await formatPromptResult(result);
+          current(owner);
+          ensureSelectedPromptCurrent();
+          ctx.signal?.throwIfAborted();
+          if (editBeforeSending) {
+            const draft = await formatEditableContent(formatted.content);
+            try {
+              current(owner);
+              ensureSelectedPromptCurrent();
+              ctx.signal?.throwIfAborted();
+              ctx.ui.pasteToEditor(draft.text);
+              owner.promptDraftCleanups.add(draft.cleanup);
+              if (draft.guard) owner.promptDraftGuards.add(draft.guard);
+            } catch (error) {
+              await draft.cleanup();
+              throw error;
+            }
+          } else {
+            pi.sendUserMessage(
+              formatted.content,
+              ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+            );
+          }
+        } finally {
+          if (ctx.mode === "tui") ctx.ui.setStatus("mcp-prompt", undefined);
+        }
       } catch (error) {
         const message =
           error instanceof Error ? error.message : "MCP prompt failed.";
@@ -150,6 +202,61 @@ export default function mcp(pi: ExtensionAPI) {
     },
   });
 
+  async function choosePrompt(
+    owner: State,
+    ctx: ExtensionCommandContext,
+  ): Promise<PromptSelection | undefined> {
+    const entries = [...owner.prompts.values()].sort(
+      (a, b) =>
+        a.server.localeCompare(b.server, "en") ||
+        a.prompt.name.localeCompare(b.prompt.name, "en"),
+    );
+    if (entries.length === 0) {
+      ctx.ui.notify("No MCP prompts are available.", "warning");
+      return;
+    }
+
+    const item = await pickPrompt(entries, ctx);
+    if (!item) return;
+    ctx.signal?.throwIfAborted();
+
+    const key = promptKey(item.server, item.prompt.name);
+    const ensureCurrent = () => {
+      current(owner);
+      if (owner.prompts.get(key) !== item)
+        throw new Error("MCP prompt catalog changed. Open the picker again.");
+    };
+    ensureCurrent();
+
+    const dialogOptions = ctx.signal ? { signal: ctx.signal } : undefined;
+    const argumentTokens: PromptArgumentToken[] = [];
+    for (const argument of item.prompt.arguments ?? []) {
+      const value = await ctx.ui.input(
+        `${argument.name} (${argument.required ? "required" : "optional"})`,
+        argument.required ? "Enter a value" : "Leave empty to omit",
+        dialogOptions,
+      );
+      if (value === undefined) return;
+      ctx.signal?.throwIfAborted();
+      ensureCurrent();
+      if (argument.required || value !== "")
+        argumentTokens.push({
+          value: `${argument.name}=${value}`,
+          separator: argument.name.length,
+        });
+    }
+
+    return {
+      command: {
+        action: "run",
+        server: item.server,
+        name: item.prompt.name,
+        argumentTokens,
+      },
+      item,
+    };
+  }
+
   function deactivate(names: Iterable<string>) {
     const removed = new Set(names);
     pi.setActiveTools(pi.getActiveTools().filter((name) => !removed.has(name)));
@@ -444,9 +551,15 @@ export default function mcp(pi: ExtensionAPI) {
     owner.alive = false;
     state = undefined;
     deactivate(owned);
-    await Promise.all(
-      [...owner.connections.values()].map((connection) => connection.close()),
-    );
+    const promptDraftCleanups = [...owner.promptDraftCleanups];
+    owner.promptDraftCleanups.clear();
+    owner.promptDraftGuards.clear();
+    await Promise.all([
+      ...[...owner.connections.values()].map((connection) =>
+        connection.close(),
+      ),
+      ...promptDraftCleanups.map((cleanup) => cleanup()),
+    ]);
   }
 
   async function start(ctx: ExtensionContext) {
@@ -460,6 +573,8 @@ export default function mcp(pi: ExtensionAPI) {
       connections: new Map(),
       rejected: new Map(),
       configIssues: [],
+      promptDraftCleanups: new Set(),
+      promptDraftGuards: new Set(),
     };
     state = owner;
     try {
@@ -514,6 +629,35 @@ export default function mcp(pi: ExtensionAPI) {
     }
   }
 
+  // Keep each invisible editor guard through Pi's command/template dispatch,
+  // then remove only guards created by this session before model context.
+  pi.on("message_end", (event) => {
+    const owner = state;
+    if (!owner || event.message.role !== "user") return;
+    const consumed = new Set<string>();
+    const removeKnownGuards = (text: string) => {
+      let next = text;
+      for (const guard of owner.promptDraftGuards) {
+        if (!next.includes(guard)) continue;
+        next = removeEditablePromptGuard(next, guard);
+        consumed.add(guard);
+      }
+      return next;
+    };
+    let content: typeof event.message.content;
+    if (typeof event.message.content === "string") {
+      content = removeKnownGuards(event.message.content);
+    } else {
+      content = event.message.content.map((block) =>
+        block.type === "text"
+          ? { ...block, text: removeKnownGuards(block.text) }
+          : block,
+      );
+    }
+    for (const guard of consumed) owner.promptDraftGuards.delete(guard);
+    if (consumed.size > 0) return { message: { ...event.message, content } };
+  });
+
   // Any extension's registerTool can reactivate allowlisted tools in Pi 0.87.
   // Independently track loaded fingerprints, enforce them in execute, and scrub
   // request-local declarations at the last provider-neutral context boundary.

package/src/output.ts

@@ -1,4 +1,5 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
@@ -70,14 +71,16 @@ export async function formatContent(
       `Structured content:\n${JSON.stringify(options.structuredContent)}`,
     );
   }
-  const fullText = text.join("\n\n") || "(No text output)";
+  const fullText =
+    text.join("\n\n") || (options.preserveOrder ? "" : "(No text output)");
   const bounded = preview(fullText);
   const structured = options.structuredContent;
   const largeDetails =
     structured !== undefined &&
     Buffer.byteLength(JSON.stringify(structured)) > MAX_DETAILS_BYTES;
+  const textTruncated = bounded !== fullText;
   const truncated =
-    bounded !== fullText ||
+    textTruncated ||
     omitted ||
     largeDetails ||
     (options.preserveErrorImages === true && images.length > 0);
@@ -99,7 +102,7 @@ export async function formatContent(
     let textIndex = 0;
     for (const block of ordered) {
       if (block.type === "image") {
-        content.push(block);
+        if (!textTruncated || offset < bounded.length) content.push(block);
         continue;
       }
       const value = `${textIndex++ > 0 ? "\n\n" : ""}${block.text}`;
@@ -112,7 +115,8 @@ export async function formatContent(
       if (previous?.type === "text") previous.text += visible;
       else content.push({ type: "text", text: visible });
     }
-    if (textIndex === 0) content.unshift({ type: "text", text: bounded });
+    if (textIndex === 0 && bounded)
+      content.unshift({ type: "text", text: bounded });
     if (artifactNotice)
       content.push({ type: "text", text: `\n\n${artifactNotice}` });
   } else {
@@ -137,6 +141,83 @@ export async function formatContent(
   };
 }
 
+function createEditablePromptGuard(): string {
+  const bytes = randomBytes(8);
+  let guard = "\u2060\u2063";
+  for (const byte of bytes)
+    for (let bit = 7; bit >= 0; bit--)
+      guard += byte & (1 << bit) ? "\u2063" : "\u2060";
+  return guard;
+}
+
+export function removeEditablePromptGuard(text: string, guard: string): string {
+  return text.replaceAll(guard, "");
+}
+
+function prepareEditablePrompt(text: string): {
+  text: string;
+  guard?: string;
+} {
+  // The TUI interprets leading / and ! as commands. An invisible guard keeps
+  // untrusted prompt text inert in the editor and is removed at message_end.
+  const sanitized = text
+    .replace(/\r\n?/gu, "\n")
+    .replace(/\p{Cc}/gu, (character) =>
+      character === "\n" || character === "\t" ? character : "",
+    )
+    .replace(/[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu, "");
+  if (!/^[!/]/u.test(sanitized.trimStart())) return { text: sanitized };
+  const guard = createEditablePromptGuard();
+  return { text: `${guard}${sanitized}`, guard };
+}
+
+const imageExtensions: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+};
+
+export async function formatEditableContent(
+  content: (TextContent | ImageContent)[],
+): Promise<{ text: string; guard?: string; cleanup: () => Promise<void> }> {
+  let text = "";
+  let imageDirectory: string | undefined;
+  let imageIndex = 0;
+  try {
+    for (const block of content) {
+      if (block.type === "text") {
+        text += block.text;
+        continue;
+      }
+      imageDirectory ??= await mkdtemp(join(tmpdir(), "pix-mcp-prompt-"));
+      const extension = imageExtensions[block.mimeType] ?? "img";
+      const path = join(
+        imageDirectory,
+        `prompt-image-${++imageIndex}.${extension}`,
+      );
+      await writeFile(path, Buffer.from(block.data, "base64"), { mode: 0o600 });
+      const separator = text.endsWith("\n\n")
+        ? ""
+        : text.endsWith("\n")
+          ? "\n"
+          : "\n\n";
+      text += `${separator}@${JSON.stringify(path.replaceAll("\\", "/"))}`;
+    }
+  } catch (error) {
+    if (imageDirectory)
+      await rm(imageDirectory, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    ...prepareEditablePrompt(text),
+    cleanup: async () => {
+      if (imageDirectory)
+        await rm(imageDirectory, { recursive: true, force: true });
+    },
+  };
+}
+
 export function formatResult(result: CallToolResult) {
   // Pi 0.87 turns thrown tool errors into text only. Preserve error images in
   // the full-result artifact before the native execution wrapper throws.

package/src/prompt-picker.ts

@@ -0,0 +1,120 @@
+import {
+  DynamicBorder,
+  type ExtensionCommandContext,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  SelectList,
+  Text,
+  type Component,
+  type SelectItem,
+  type TUI,
+  type TuiMouseEvent,
+} from "@earendil-works/pi-tui";
+import { compact } from "./catalog.ts";
+import { promptKey, type PromptEntry } from "./prompts.ts";
+
+function details(entry: PromptEntry, theme: Theme): string {
+  const title = compact(entry.prompt.title ?? "", 120);
+  const description = compact(entry.prompt.description ?? "", 320);
+  return [
+    ...(title ? [theme.fg("accent", theme.bold(title))] : []),
+    theme.fg(
+      description ? "muted" : "dim",
+      description || "No description provided.",
+    ),
+  ].join("\n");
+}
+
+export function createPromptPicker(
+  entries: PromptEntry[],
+  tui: TUI,
+  theme: Theme,
+  done: (result: string | undefined) => void,
+  signal?: AbortSignal,
+): Component & { dispose(): void } {
+  const items: SelectItem[] = entries.map((entry) => ({
+    value: promptKey(entry.server, entry.prompt.name),
+    label: `${entry.server} / ${entry.prompt.name}`,
+  }));
+  const entriesByKey = new Map(
+    entries.map((entry) => [promptKey(entry.server, entry.prompt.name), entry]),
+  );
+  const container = new Container();
+  container.addChild(new DynamicBorder((text) => theme.fg("accent", text)));
+  container.addChild(
+    new Text(theme.fg("accent", theme.bold("Select MCP prompt"))),
+  );
+
+  const list = new SelectList(items, Math.min(items.length, 10), {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+    scrollInfo: (text) => theme.fg("dim", text),
+    noMatch: (text) => theme.fg("warning", text),
+  });
+  container.addChild(list);
+
+  const focusedDescription = new Text("", 1, 1);
+  const updateDescription = (item: SelectItem) => {
+    const entry = entriesByKey.get(item.value);
+    if (entry) focusedDescription.setText(details(entry, theme));
+  };
+  const initialItem = items[0];
+  if (initialItem) updateDescription(initialItem);
+  list.onSelectionChange = updateDescription;
+  container.addChild(focusedDescription);
+  container.addChild(
+    new Text(theme.fg("dim", "↑↓ navigate • enter select • esc cancel")),
+  );
+  container.addChild(new DynamicBorder((text) => theme.fg("accent", text)));
+
+  let finished = false;
+  const finish = (result: string | undefined) => {
+    if (finished) return;
+    finished = true;
+    done(result);
+  };
+  list.onSelect = (item) => finish(item.value);
+  list.onCancel = () => finish(undefined);
+  const onAbort = () => finish(undefined);
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+
+  return {
+    render(width: number) {
+      return container.render(width);
+    },
+    invalidate() {
+      container.invalidate();
+    },
+    handleInput(data: string) {
+      list.handleInput(data);
+      tui.requestRender();
+    },
+    handleMouse(event: TuiMouseEvent) {
+      const result = container.handleMouse(event);
+      if (result?.render) tui.requestRender();
+      return result;
+    },
+    dispose() {
+      signal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+export async function pickPrompt(
+  entries: PromptEntry[],
+  ctx: ExtensionCommandContext,
+): Promise<PromptEntry | undefined> {
+  if (ctx.signal?.aborted) return;
+  const selected = await ctx.ui.custom<string | undefined>(
+    (tui, theme, _keybindings, done) =>
+      createPromptPicker(entries, tui, theme, done, ctx.signal),
+  );
+  if (selected === undefined) return;
+  return entries.find(
+    (entry) => promptKey(entry.server, entry.prompt.name) === selected,
+  );
+}

package/src/prompts.ts

@@ -322,21 +322,29 @@ function tokenize(input: string): PromptArgumentToken[] {
   return tokens;
 }
 
-export async function formatPromptResult(
-  result: GetPromptResult,
-  server: string,
-  name: string,
-) {
+function hasUsablePromptContent(
+  content: GetPromptResult["messages"][number]["content"],
+): boolean {
+  if (content.type === "text") return content.text.trim().length > 0;
+  if (content.type === "resource")
+    return "text" in content.resource
+      ? content.resource.text.trim().length > 0
+      : content.resource.blob.length > 0;
+  if (content.type === "resource_link") return content.uri.trim().length > 0;
+  return content.data.length > 0;
+}
+
+export async function formatPromptResult(result: GetPromptResult) {
   if (result.messages.length === 0)
     throw new Error("MCP prompt returned no messages.");
-  const blocks: ContentBlock[] = [
-    { type: "text", text: `[MCP prompt from ${server}/${name}]` },
-  ];
+  const blocks: ContentBlock[] = [];
+  let hasSourceContent = false;
   const showRoles =
     result.messages.length > 1 || result.messages[0]?.role !== "user";
   for (const message of result.messages) {
     if (showRoles) blocks.push({ type: "text", text: `[${message.role}]` });
     const content = message.content;
+    if (hasUsablePromptContent(content)) hasSourceContent = true;
     if (content.type === "resource") {
       if ("text" in content.resource) {
         blocks.push({
@@ -362,5 +370,13 @@ export async function formatPromptResult(
       });
     } else blocks.push(content);
   }
-  return formatContent(blocks, { artifact: result, preserveOrder: true });
+  if (!hasSourceContent)
+    throw new Error("MCP prompt returned no usable content.");
+  const formatted = await formatContent(blocks, {
+    artifact: result,
+    preserveOrder: true,
+  });
+  if (formatted.content.length === 0)
+    throw new Error("MCP prompt returned no usable content.");
+  return formatted;
 }