@asterxsk/kiln 0.1.0

package/agent/extensions/ask-user/index.ts

@@ -0,0 +1,418 @@
+/**
+ * ask_user - Lets the model ask a single multiple-choice question.
+ *
+ * - 2 to 5 model-provided options, plus an always-present "Write my own answer" option
+ * - Popup UI: arrow keys or number keys to pick, Enter to confirm
+ * - "Write my own answer" opens an inline editor (Esc returns to the options)
+ * - Esc on the options dismisses the question (the model is told you declined)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  Editor,
+  type EditorTheme,
+  Key,
+  matchesKey,
+  Text,
+  truncateToWidth,
+} from "@earendil-works/pi-tui";
+import { Cause, Effect, Exit } from "effect";
+import { Type, type Static } from "typebox";
+import {
+  ASK_USER_PARAMETER_DESCRIPTIONS,
+  ASK_USER_PROMPT_GUIDELINES,
+  ASK_USER_PROMPT_SNIPPET,
+  ASK_USER_TOOL_DESCRIPTION,
+  buildAskUserResultMessage,
+} from "./prompt.ts";
+
+const MIN_OPTIONS = 2;
+const MAX_OPTIONS = 5;
+
+const OptionSchema = Type.Object({
+  label: Type.String({
+    description: ASK_USER_PARAMETER_DESCRIPTIONS.optionLabel,
+  }),
+  description: Type.Optional(
+    Type.String({
+      description: ASK_USER_PARAMETER_DESCRIPTIONS.optionDescription,
+    }),
+  ),
+});
+
+const AskUserParams = Type.Object({
+  question: Type.String({
+    description: ASK_USER_PARAMETER_DESCRIPTIONS.question,
+  }),
+  options: Type.Array(OptionSchema, {
+    minItems: MIN_OPTIONS,
+    maxItems: MAX_OPTIONS,
+    description: ASK_USER_PARAMETER_DESCRIPTIONS.options,
+  }),
+});
+
+export type AskUserInput = Static<typeof AskUserParams>;
+
+interface AskUserDetails {
+  question: string;
+  options: string[];
+  answer: string | null;
+  wasCustom: boolean;
+  cancelled: boolean;
+}
+
+type SelectionResult = {
+  answer: string;
+  wasCustom: boolean;
+  index?: number;
+} | null;
+
+interface DisplayOption {
+  label: string;
+  description?: string;
+  isOther?: boolean;
+}
+
+function wrapText(text: string, width: number): string[] {
+  const lines: string[] = [];
+  for (const paragraph of text.split("\n")) {
+    const words = paragraph.split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let current = "";
+    for (const word of words) {
+      const candidate = current ? `${current} ${word}` : word;
+      if (candidate.length > width && current) {
+        lines.push(current);
+        current = word;
+      } else {
+        current = candidate;
+      }
+    }
+    if (current) lines.push(current);
+  }
+  return lines;
+}
+
+export default function askUser(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "ask_user",
+    label: "Ask User",
+    description: ASK_USER_TOOL_DESCRIPTION,
+    promptSnippet: ASK_USER_PROMPT_SNIPPET,
+    promptGuidelines: ASK_USER_PROMPT_GUIDELINES,
+    parameters: AskUserParams,
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const reply = (
+        text: string,
+        answer: string | null = null,
+        wasCustom = false,
+      ) => ({
+        content: [{ type: "text" as const, text }],
+        details: {
+          question: params.question,
+          options: params.options.map((o) => o.label),
+          answer,
+          wasCustom,
+          cancelled: answer === null,
+        } satisfies AskUserDetails,
+      });
+
+      if (
+        params.options.length < MIN_OPTIONS ||
+        params.options.length > MAX_OPTIONS
+      ) {
+        throw new Error(
+          `ask_user requires between ${MIN_OPTIONS} and ${MAX_OPTIONS} options (got ${params.options.length}). Retry with a valid number of options.`,
+        );
+      }
+
+      if (ctx.mode !== "tui") {
+        return reply(buildAskUserResultMessage({ kind: "no-ui" }));
+      }
+
+      if (signal?.aborted) {
+        return reply(buildAskUserResultMessage({ kind: "cancelled" }));
+      }
+
+      const allOptions: DisplayOption[] = [
+        ...params.options,
+        { label: "Write my own answer…", isOther: true },
+      ];
+
+      const showQuestion = (uiSignal: AbortSignal) =>
+        ctx.ui.custom<SelectionResult>((tui, theme, _kb, done) => {
+          let optionIndex = 0;
+          let editMode = false;
+          let cachedLines: string[] | undefined;
+
+          let settled = false;
+
+          function finish(result: SelectionResult) {
+            if (settled) return;
+            settled = true;
+            uiSignal.removeEventListener("abort", cancel);
+            done(result);
+          }
+
+          function cancel() {
+            finish(null);
+          }
+
+          uiSignal.addEventListener("abort", cancel, { once: true });
+          if (uiSignal.aborted) queueMicrotask(cancel);
+
+          const editorTheme: EditorTheme = {
+            borderColor: (s) => theme.fg("accent", s),
+            selectList: {
+              selectedPrefix: (t) => theme.fg("accent", t),
+              selectedText: (t) => theme.fg("accent", t),
+              description: (t) => theme.fg("muted", t),
+              scrollInfo: (t) => theme.fg("dim", t),
+              noMatch: (t) => theme.fg("warning", t),
+            },
+          };
+          const editor = new Editor(tui, editorTheme);
+
+          editor.onSubmit = (value) => {
+            const trimmed = value.trim();
+            if (trimmed) {
+              finish({ answer: trimmed, wasCustom: true });
+            } else {
+              editMode = false;
+              editor.setText("");
+              refresh();
+            }
+          };
+
+          function refresh() {
+            cachedLines = undefined;
+            tui.requestRender();
+          }
+
+          function selectOption(index: number) {
+            const selected = allOptions[index];
+            if (selected.isOther) {
+              optionIndex = index;
+              editMode = true;
+              refresh();
+            } else {
+              finish({
+                answer: selected.label,
+                wasCustom: false,
+                index: index + 1,
+              });
+            }
+          }
+
+          function handleInput(data: string) {
+            if (editMode) {
+              if (matchesKey(data, Key.escape)) {
+                editMode = false;
+                editor.setText("");
+                refresh();
+                return;
+              }
+              editor.handleInput(data);
+              refresh();
+              return;
+            }
+
+            if (matchesKey(data, Key.up)) {
+              optionIndex =
+                (optionIndex - 1 + allOptions.length) % allOptions.length;
+              refresh();
+              return;
+            }
+            if (matchesKey(data, Key.down)) {
+              optionIndex = (optionIndex + 1) % allOptions.length;
+              refresh();
+              return;
+            }
+
+            // Number keys jump straight to an option
+            if (
+              data.length === 1 &&
+              data >= "1" &&
+              data <= String(allOptions.length)
+            ) {
+              selectOption(Number(data) - 1);
+              return;
+            }
+
+            if (matchesKey(data, Key.enter)) {
+              selectOption(optionIndex);
+              return;
+            }
+
+            if (matchesKey(data, Key.escape)) {
+              finish(null);
+            }
+          }
+
+          function render(width: number): string[] {
+            if (cachedLines) return cachedLines;
+
+            const lines: string[] = [];
+            const add = (s: string) => lines.push(truncateToWidth(s, width));
+
+            const title = " Question ";
+            add(
+              theme.fg(
+                "accent",
+                `─${title}${"─".repeat(Math.max(0, width - title.length - 1))}`,
+              ),
+            );
+            for (const line of wrapText(
+              params.question,
+              Math.max(10, width - 2),
+            )) {
+              add(` ${theme.fg("text", theme.bold(line))}`);
+            }
+            lines.push("");
+
+            for (let i = 0; i < allOptions.length; i++) {
+              const opt = allOptions[i];
+              const selected = i === optionIndex;
+              const prefix = selected ? theme.fg("accent", " ❯ ") : "   ";
+              const marker = opt.isOther ? "✎" : `${i + 1}.`;
+              const label = `${marker} ${opt.label}`;
+
+              if (selected || (opt.isOther && editMode)) {
+                add(prefix + theme.fg("accent", label));
+              } else {
+                add(prefix + theme.fg(opt.isOther ? "muted" : "text", label));
+              }
+
+              if (opt.description) {
+                add(`      ${theme.fg("muted", opt.description)}`);
+              }
+            }
+
+            if (editMode) {
+              lines.push("");
+              add(theme.fg("muted", " Your answer:"));
+              for (const line of editor.render(width - 2)) {
+                add(` ${line}`);
+              }
+            }
+
+            lines.push("");
+            if (editMode) {
+              add(theme.fg("dim", " Enter submit • Esc back to options"));
+            } else {
+              add(
+                theme.fg(
+                  "dim",
+                  ` ↑↓ or 1-${allOptions.length} select • Enter confirm • Esc dismiss`,
+                ),
+              );
+            }
+            add(theme.fg("accent", "─".repeat(width)));
+
+            cachedLines = lines;
+            return lines;
+          }
+
+          return {
+            render,
+            invalidate: () => {
+              cachedLines = undefined;
+            },
+            handleInput,
+            dispose: () => {
+              uiSignal.removeEventListener("abort", cancel);
+            },
+          };
+        });
+
+      const uiExit = await Effect.runPromiseExit(
+        Effect.tryPromise(showQuestion),
+        signal ? { signal } : undefined,
+      );
+
+      if (Exit.isFailure(uiExit)) {
+        if (Cause.hasInterruptsOnly(uiExit.cause)) {
+          return reply(buildAskUserResultMessage({ kind: "cancelled" }));
+        }
+        const [first] = Cause.prettyErrors(uiExit.cause);
+        throw new Error(first?.message ?? Cause.pretty(uiExit.cause));
+      }
+
+      const result = uiExit.value;
+
+      if (!result) {
+        return reply(buildAskUserResultMessage({ kind: "dismissed" }));
+      }
+
+      if (result.wasCustom) {
+        return reply(
+          buildAskUserResultMessage({
+            kind: "custom",
+            answer: result.answer,
+          }),
+          result.answer,
+          true,
+        );
+      }
+
+      return reply(
+        buildAskUserResultMessage({
+          kind: "selected",
+          answer: result.answer,
+          index: result.index,
+        }),
+        result.answer,
+      );
+    },
+
+    renderCall(args, theme, _context) {
+      let text = theme.fg("toolTitle", theme.bold("ask_user "));
+      text += theme.fg(
+        "muted",
+        typeof args.question === "string" ? args.question : "",
+      );
+      const opts = Array.isArray(args.options)
+        ? (args.options as DisplayOption[])
+        : [];
+      if (opts.length > 0) {
+        const numbered = opts.map((o, i) => `${i + 1}. ${o.label}`);
+        text += `\n${theme.fg("dim", `  ${numbered.join("  ")}`)}`;
+      }
+      return new Text(text, 1, 0);
+    },
+
+    renderResult(result, _options, theme, _context) {
+      const details = result.details as AskUserDetails | undefined;
+      if (!details) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "", 1, 0);
+      }
+
+      if (details.cancelled || details.answer === null) {
+        return new Text(theme.fg("warning", "✗ dismissed"), 1, 0);
+      }
+
+      if (details.wasCustom) {
+        return new Text(
+          theme.fg("success", "✓ ") +
+            theme.fg("muted", "(wrote) ") +
+            theme.fg("accent", details.answer),
+          1,
+          0,
+        );
+      }
+
+      const idx = details.options.indexOf(details.answer) + 1;
+      const display = idx > 0 ? `${idx}. ${details.answer}` : details.answer;
+      return new Text(
+        theme.fg("success", "✓ ") + theme.fg("accent", display),
+        1,
+        0,
+      );
+    },
+  });
+}

package/agent/extensions/ask-user/install.ps1

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent/extensions/ask-user/install.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"