@rol1n/pi-kit 0.0.0-stage → 0.1.1

package/ask-u-questions/single-choice.ts

@@ -0,0 +1,180 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Editor, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getOtherLabel, isChineseContext, type AskAnswer, type AskOption, type DisplayOption } from "./types.ts";
+import { addWrapped, createEditorTheme } from "./dialog-ui.ts";
+
+export async function askSingleChoice(
+  ctx: ExtensionContext,
+  question: string,
+  context: string | undefined,
+  options: AskOption[],
+): Promise<AskAnswer | null> {
+  const isZh = isChineseContext(question, options, context);
+  const otherLabel = getOtherLabel(options, isZh);
+  const allOptions: DisplayOption[] = [
+    ...options.map((option, index) => ({
+      ...option,
+      id: `option:${index}`,
+      index: index + 1,
+    })),
+    { id: "other", label: otherLabel, value: "__other__", isOther: true },
+  ];
+
+  return ctx.ui.custom<AskAnswer | null>(
+    (tui, theme, _kb, done: (result: AskAnswer | null) => void) => {
+      let optionIndex = 0;
+      let editMode = false;
+      let cachedLines: string[] | undefined;
+      let cachedWidth = -1;
+      let componentFocused = false;
+      const editor = new Editor(tui, createEditorTheme(theme));
+
+      editor.onSubmit = (value) => {
+        const trimmed = value.trim();
+        if (!trimmed) return;
+        done({ type: "other", label: trimmed, value: trimmed });
+      };
+
+      function refresh() {
+        cachedLines = undefined;
+        tui.requestRender();
+      }
+
+      function handleInput(data: string) {
+        if (editMode) {
+          if (matchesKey(data, Key.escape)) {
+            editMode = false;
+            editor.focused = false;
+            editor.setText("");
+            refresh();
+            return;
+          }
+          editor.handleInput(data);
+          refresh();
+          return;
+        }
+
+        if (matchesKey(data, Key.up)) {
+          optionIndex = Math.max(0, optionIndex - 1);
+          refresh();
+          return;
+        }
+        if (matchesKey(data, Key.down)) {
+          optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);
+          refresh();
+          return;
+        }
+        if (matchesKey(data, Key.enter)) {
+          const selected = allOptions[optionIndex];
+          if (selected.isOther) {
+            editMode = true;
+            editor.focused = componentFocused;
+            editor.setText("");
+            refresh();
+            return;
+          }
+          done({
+            type: "option",
+            label: selected.label,
+            value: selected.value,
+            index: selected.index!,
+          });
+          return;
+        }
+        if (matchesKey(data, Key.escape)) {
+          done(null);
+        }
+      }
+
+      function render(width: number): string[] {
+        if (cachedLines && cachedWidth === width) return cachedLines;
+
+        const lines: string[] = [];
+        const add = (text: string) => lines.push(truncateToWidth(text, width));
+
+        add(theme.fg("accent", "─".repeat(width)));
+
+        if (editMode) {
+          addWrapped(lines, question, width, " ", " ", (l) => theme.fg("text", theme.bold(l)));
+          if (context) {
+            addWrapped(lines, context, width, " ", " ", (l) => theme.fg("muted", l));
+          }
+          lines.push("");
+          const header = allOptions[optionIndex]?.label || otherLabel;
+          add(theme.fg("accent", ` > ${header}:`));
+          for (const line of editor.render(Math.max(1, width - 4))) {
+            add(`   ${line}`);
+          }
+          lines.push("");
+          const editHint = isZh
+            ? " Enter 提交 • Esc 返回选项"
+            : " Enter to submit • Esc to return";
+          add(theme.fg("dim", editHint));
+          add(theme.fg("accent", "─".repeat(width)));
+          cachedLines = lines;
+          cachedWidth = width;
+          return lines;
+        }
+
+        addWrapped(lines, question, width, " ", " ", (l) => theme.fg("text", theme.bold(l)));
+        if (context) {
+          addWrapped(lines, context, width, " ", " ", (l) => theme.fg("muted", l));
+        }
+        lines.push("");
+
+        for (let i = 0; i < allOptions.length; i++) {
+          const item = allOptions[i];
+          const selected = i === optionIndex;
+          const prefix = selected ? theme.fg("accent", " > ") : "   ";
+
+          if (item.isOther) {
+            const styledLabel = selected
+              ? theme.bold(theme.fg("accent", item.label))
+              : theme.fg("text", item.label);
+            lines.push(truncateToWidth(`${prefix}${styledLabel}`, width));
+          } else {
+            const numPrefix = `${item.index}. `;
+            const firstIndent = `${prefix}${selected ? theme.fg("accent", numPrefix) : numPrefix}`;
+            const restIndent = " ".repeat(visibleWidth(firstIndent));
+            const styleLabel = (l: string) =>
+              selected ? theme.bold(theme.fg("accent", l)) : theme.fg("text", l);
+
+            addWrapped(lines, item.label, width, firstIndent, restIndent, styleLabel);
+
+            if (item.description) {
+              const descIndent = " ".repeat(visibleWidth(firstIndent));
+              const descStyle = (l: string) => theme.fg("muted", l);
+              addWrapped(lines, item.description, width, descIndent, descIndent, descStyle);
+            }
+          }
+        }
+
+        lines.push("");
+        const navHint = isZh
+          ? " ↑↓ 选择 • Enter 确定 • Esc 取消"
+          : " ↑↓ to navigate • Enter to select • Esc to cancel";
+        add(theme.fg("dim", navHint));
+        add(theme.fg("accent", "─".repeat(width)));
+
+        cachedLines = lines;
+        cachedWidth = width;
+        return lines;
+      }
+
+      return {
+        render,
+        invalidate: () => {
+          cachedLines = undefined;
+        },
+        handleInput,
+        get focused(): boolean {
+          return componentFocused;
+        },
+        set focused(value: boolean) {
+          componentFocused = value;
+          editor.focused = editMode && componentFocused;
+        },
+      };
+    },
+  );
+}

package/ask-u-questions/tool-renderers.ts

@@ -0,0 +1,67 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { AskUserQuestionParams, getOtherLabel, isChineseContext, normalizeOptions, type AskUserQuestionResultDetails } from "./types.ts";
+
+export const questionRenderers: Pick<ToolDefinition<typeof AskUserQuestionParams, AskUserQuestionResultDetails>, "renderCall" | "renderResult"> = {
+  renderCall(args, theme, context) {
+    const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+    const options = normalizeOptions(
+      args.options as Array<{ label: string; value?: string; description?: string }> | undefined,
+    );
+    const isZh = isChineseContext(args.question || "", options, args.details);
+    let summary =
+      theme.fg("toolTitle", theme.bold("ask_user_question ")) +
+      theme.fg("accent", `"${args.question || ""}"`);
+    if (args.multiSelect) {
+      summary += theme.fg("dim", " [multi-select]");
+    }
+    if (options.length > 0) {
+      const otherLbl = getOtherLabel(options, isZh);
+      const labels = [...options.map((option) => option.label), otherLbl].join(", ");
+      const optPrefix = isZh ? "  选项: " : "  Options: ";
+      summary += `\n${theme.fg("dim", `${optPrefix}${labels}`)}`;
+    }
+    text.setText(summary);
+    return text;
+  },
+
+  renderResult(result, _options, theme, context) {
+    const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+    const details = result.details as AskUserQuestionResultDetails | undefined;
+    if (!details) {
+      const first = result.content?.[0];
+      text.setText(first?.type === "text" ? first.text : "");
+      return text;
+    }
+
+    const isZh = isChineseContext(details.question || "", details.answers, details.context);
+
+    if (details.status === "cancelled") {
+      const defaultCancelled = isZh ? "已取消" : "Cancelled";
+      text.setText(theme.fg("warning", `⊘ ${details.message || defaultCancelled}`));
+      return text;
+    }
+
+    if (details.status === "unavailable") {
+      const defaultUnavailable = isZh ? "提问工具不可用" : "Tool unavailable";
+      text.setText(theme.fg("error", `! ${details.message || defaultUnavailable}`));
+      return text;
+    }
+
+    const emptyText = isZh ? "(空回答)" : "(empty)";
+    const otherPrefix = isZh ? "其他：" : "Other: ";
+
+    const lines = details.answers.map((answer) => {
+      switch (answer.type) {
+        case "text":
+          return `${theme.fg("success", "✓ ")}${theme.fg("accent", answer.label || emptyText)}`;
+        case "other":
+          return `${theme.fg("success", "✓ ")}${theme.fg("muted", otherPrefix)}${theme.fg("accent", answer.label)}`;
+        case "option":
+          return `${theme.fg("success", "✓ ")}${theme.fg("accent", `${answer.index}. ${answer.label}`)}`;
+      }
+    });
+    text.setText(lines.join("\n"));
+    return text;
+  },
+};

package/ask-u-questions/types.ts

@@ -0,0 +1,192 @@
+import { Type } from "typebox";
+
+const OptionSchema = Type.Object({
+  label: Type.String({ description: 'Option label. Put a recommended option first and append "(Recommended)".' }),
+  value: Type.Optional(Type.String({ description: "Machine-readable value; defaults to the label." })),
+  description: Type.Optional(Type.String({ description: "Additional context shown below the option." })),
+});
+
+export const AskUserQuestionParams = Type.Object({
+  question: Type.String({ description: "The question to ask. Ask only one question per call." }),
+  details: Type.Optional(Type.String({ description: "Background or instructions shown below the question." })),
+  options: Type.Optional(Type.Array(OptionSchema, {
+    description: "Choices for selection. Omit or pass an empty array for free-text input. An Other choice is always available.",
+  })),
+  multiSelect: Type.Optional(Type.Boolean({ description: "Allow selecting multiple options when true." })),
+});
+
+export interface AskOption {
+  label: string;
+  value: string;
+  description?: string;
+}
+
+export interface DisplayOption extends AskOption {
+  id: string;
+  index?: number;
+  isOther?: boolean;
+  isSubmit?: boolean;
+}
+
+export interface TextAnswer {
+  type: "text";
+  label: string;
+  value: string;
+}
+
+export interface OptionAnswer {
+  type: "option";
+  label: string;
+  value: string;
+  index: number;
+}
+
+export interface OtherAnswer {
+  type: "other";
+  label: string;
+  value: string;
+}
+
+export type AskAnswer = TextAnswer | OptionAnswer | OtherAnswer;
+export type AskUserQuestionStatus = "answered" | "cancelled" | "unavailable";
+export type AskUserQuestionMode = "text" | "single-select" | "multi-select";
+
+export interface AskUserQuestionResultDetails {
+  status: AskUserQuestionStatus;
+  question: string;
+  context?: string;
+  mode: AskUserQuestionMode;
+  answers: AskAnswer[];
+  message?: string;
+}
+
+export function normalizeOptions(
+  options: Array<{ label: string; value?: string; description?: string }> | undefined,
+): AskOption[] {
+  return (options || [])
+    .map((option) => ({
+      label: option.label.trim(),
+      value: option.value?.trim() || option.label.trim(),
+      description: option.description?.trim() || undefined,
+    }))
+    .filter((option) => option.label.length > 0);
+}
+
+export function isChineseContext(
+  question: string,
+  options?: Array<{ label?: string; description?: string }>,
+  context?: string,
+): boolean {
+  if (/[\u4e00-\u9fa5]/.test(question)) return true;
+  if (context && /[\u4e00-\u9fa5]/.test(context)) return true;
+  if (options && options.some((o) => (o.label && /[\u4e00-\u9fa5]/.test(o.label)) || (o.description && /[\u4e00-\u9fa5]/.test(o.description)))) {
+    return true;
+  }
+  return false;
+}
+
+export function getOtherLabel(options: AskOption[], isZh = false): string {
+  if (isZh) {
+    return options.some((option) => option.label === "其他（自定义输入）")
+      ? "自定义输入"
+      : "其他（自定义输入）";
+  }
+  return options.some((option) => option.label === "Other (custom input)")
+    ? "Custom input"
+    : "Other (custom input)";
+}
+
+function answerSortRank(answer: AskAnswer): number {
+  switch (answer.type) {
+    case "option":
+      return answer.index;
+    case "other":
+      return Number.MAX_SAFE_INTEGER - 1;
+    case "text":
+      return Number.MAX_SAFE_INTEGER;
+  }
+}
+
+export function sortAnswers(answers: AskAnswer[]): AskAnswer[] {
+  return [...answers].sort((a, b) => answerSortRank(a) - answerSortRank(b));
+}
+
+function formatAnswerForModel(answer: AskAnswer): string {
+  switch (answer.type) {
+    case "text":
+      return answer.label;
+    case "other":
+      return `Other: ${answer.label}`;
+    case "option":
+      return `${answer.index}. ${answer.label}`;
+  }
+}
+
+function buildStructuredResult(
+  status: AskUserQuestionStatus,
+  question: string,
+  mode: AskUserQuestionMode,
+  answers: AskAnswer[],
+  context?: string,
+  message?: string,
+): AskUserQuestionResultDetails {
+  return {
+    status,
+    question,
+    context,
+    mode,
+    answers,
+    message,
+  };
+}
+
+export function cancelledResult(question: string, mode: AskUserQuestionMode, context?: string) {
+  const isZh = isChineseContext(question, undefined, context);
+  const message = isZh ? "用户取消了本次提问" : "User cancelled the question.";
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: buildStructuredResult("cancelled", question, mode, [], context, message),
+  };
+}
+
+export function unavailableResult(question: string, mode: AskUserQuestionMode, message: string, context?: string) {
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: buildStructuredResult("unavailable", question, mode, [], context, message),
+  };
+}
+
+export function buildResult(
+  question: string,
+  context: string | undefined,
+  mode: AskUserQuestionMode,
+  answers: AskAnswer[],
+) {
+  const isZh = isChineseContext(question, answers, context);
+  let text: string;
+  if (mode === "text") {
+    const answer = answers[0];
+    if (isZh) {
+      text = answer.label.trim().length > 0
+        ? `用户输入回答: ${answer.label}`
+        : "用户提交了空回答";
+    } else {
+      text = answer.label.trim().length > 0
+        ? `User answered: ${answer.label}`
+        : "User submitted an empty answer";
+    }
+  } else if (mode === "single-select") {
+    text = isZh
+      ? `用户选择项: ${formatAnswerForModel(answers[0])}`
+      : `User selected: ${formatAnswerForModel(answers[0])}`;
+  } else {
+    text = isZh
+      ? `用户选择多项:\n${answers.map((answer) => `- ${formatAnswerForModel(answer)}`).join("\n")}`
+      : `User selected multiple:\n${answers.map((answer) => `- ${formatAnswerForModel(answer)}`).join("\n")}`;
+  }
+
+  return {
+    content: [{ type: "text" as const, text }],
+    details: buildStructuredResult("answered", question, mode, answers, context),
+  };
+}

package/continue-signal/README.md

@@ -0,0 +1,20 @@
+# continue-signal
+
+Resume an idle Pi agent with a visible continuation signal.
+
+## Install
+
+```sh
+pi install npm:@rol1n/continue-signal
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Commands and shortcuts
+
+| Action | Trigger |
+|---|---|
+| Resume unfinished work | `/continue` or `Alt+C` |
+| Resume with custom instruction | `/continue Review the remaining test failures` |
+
+An explicit command argument takes priority; otherwise the current editor draft is consumed, falling back to a default resume prompt.

package/continue-signal/index.ts

@@ -0,0 +1,69 @@
+/**
+ * continue-signal — Resume an idle agent via /continue [prompt] or Alt+C.
+ * Uses the editor draft when no prompt is supplied.
+ */
+
+import type { ExtensionAPI, ExtensionContext, MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Key, Text } from "@earendil-works/pi-tui";
+
+const DEFAULT_PROMPT = "Review the conversation context and resume any unfinished work from where it stopped.";
+const CUSTOM_TYPE = "continue-signal";
+
+const renderContinueSignal: MessageRenderer<{ timestamp?: number }> = (
+  message,
+  { expanded, outputPad },
+  theme,
+) => {
+  const time = new Date(message.details?.timestamp ?? Date.now()).toLocaleTimeString();
+  const title = `${theme.bold(theme.fg("accent", "⚡ LOOP RESUME SIGNAL"))} ${theme.fg("muted", `[${time}]` )}`;
+
+  const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(title, 0, 0));
+  box.addChild(new Text(theme.fg("text", "Re-linking conversation context & resuming agent loop..."), 0, 0));
+
+  if (expanded && message.content) {
+    box.addChild(new Text(theme.fg("dim", `Prompt: ${message.content}`), 0, 0));
+  }
+
+  return box;
+};
+
+export default function (pi: ExtensionAPI) {
+  pi.registerMessageRenderer(CUSTOM_TYPE, renderContinueSignal);
+
+  const triggerContinue = (ctx: ExtensionContext, customPrompt = "") => {
+    if (!ctx.isIdle()) {
+      ctx.ui.notify("Agent is currently running; no need to wake up.", "warning");
+      return;
+    }
+
+    let prompt = customPrompt.trim();
+    if (!prompt) {
+      const draft = ctx.ui.getEditorText?.()?.trim();
+      if (draft) {
+        prompt = draft;
+        ctx.ui.setEditorText?.("");
+      }
+    }
+
+    pi.sendMessage(
+      {
+        customType: CUSTOM_TYPE,
+        content: prompt || DEFAULT_PROMPT,
+        display: true,
+        details: { timestamp: Date.now() },
+      },
+      { triggerTurn: true, deliverAs: "steer" },
+    );
+  };
+
+  pi.registerCommand("continue", {
+    description: "Send a resume signal to continue unfinished work (optional prompt)",
+    handler: (args, ctx) => triggerContinue(ctx, args),
+  });
+
+  pi.registerShortcut(Key.alt("c"), {
+    description: "Resume unfinished work",
+    handler: (ctx) => triggerContinue(ctx),
+  });
+}

package/custom-providers/README.md

@@ -0,0 +1,20 @@
+# custom-providers
+
+Registers additional model providers through Pi's native model registry and `/login` interface.
+
+## Install
+
+```sh
+pi install npm:@rol1n/custom-providers
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Providers
+
+| Provider | Configuration |
+|---|---|
+| Magpie | `MAGPIE_BASE_URL` (default `http://127.0.0.1:3425/v1`); authenticate via `MAGPIE_GATEWAY_KEY` or `/login magpie` |
+| SHUAI API | Authenticate via `/login shuaiapi` |
+| BigModel | Authenticate via `/login bigmodel` |
+| DashScope | Authenticate via `/login dashscope`; `DASHSCOPE_IMAGE_URL` overrides the image API base URL |