@pi-unipi/ask-user 0.1.1

package/config.ts

@@ -0,0 +1,133 @@
+/**
+ * @pi-unipi/ask-user — Config system
+ *
+ * Reads/writes ask-user settings in ~/.pi/agent/settings.json
+ * under the "unipi.askUser" key.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** Ask-user settings */
+export interface AskUserSettings {
+  /** Whether the ask_user tool is enabled */
+  enabled: boolean;
+  /** Allowed question formats */
+  allowedFormats: {
+    /** Allow single-select questions */
+    singleSelect: boolean;
+    /** Allow multi-select questions */
+    multiSelect: boolean;
+    /** Allow freeform text input */
+    freeform: boolean;
+  };
+}
+
+/** Default settings */
+export const DEFAULT_SETTINGS: AskUserSettings = {
+  enabled: true,
+  allowedFormats: {
+    singleSelect: true,
+    multiSelect: true,
+    freeform: true,
+  },
+};
+
+/** Settings path */
+const SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+
+/** Settings key within settings.json */
+const SETTINGS_KEY = "unipi";
+
+/** Cached settings */
+let cachedSettings: AskUserSettings | null = null;
+
+/**
+ * Check if value is a plain object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read the full settings file.
+ */
+function readSettingsFile(): Record<string, unknown> {
+  if (!existsSync(SETTINGS_PATH)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write the full settings file.
+ */
+function writeSettingsFile(data: Record<string, unknown>): void {
+  const dir = require("node:path").dirname(SETTINGS_PATH);
+  if (!existsSync(dir)) {
+    require("node:fs").mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(SETTINGS_PATH, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Get ask-user settings from settings.json.
+ */
+export function getAskUserSettings(): AskUserSettings {
+  if (cachedSettings) return cachedSettings;
+
+  const settings = readSettingsFile();
+  const unipi = settings[SETTINGS_KEY];
+
+  if (!isRecord(unipi) || !isRecord(unipi.askUser)) {
+    cachedSettings = { ...DEFAULT_SETTINGS };
+    return cachedSettings;
+  }
+
+  const askUser = unipi.askUser as Record<string, unknown>;
+
+  const enabled = typeof askUser.enabled === "boolean" ? askUser.enabled : DEFAULT_SETTINGS.enabled;
+
+  let allowedFormats = DEFAULT_SETTINGS.allowedFormats;
+  if (isRecord(askUser.allowedFormats)) {
+    const fmt = askUser.allowedFormats;
+    allowedFormats = {
+      singleSelect: typeof fmt.singleSelect === "boolean" ? fmt.singleSelect : DEFAULT_SETTINGS.allowedFormats.singleSelect,
+      multiSelect: typeof fmt.multiSelect === "boolean" ? fmt.multiSelect : DEFAULT_SETTINGS.allowedFormats.multiSelect,
+      freeform: typeof fmt.freeform === "boolean" ? fmt.freeform : DEFAULT_SETTINGS.allowedFormats.freeform,
+    };
+  }
+
+  cachedSettings = { enabled, allowedFormats };
+  return cachedSettings;
+}
+
+/**
+ * Save ask-user settings to settings.json.
+ */
+export function saveAskUserSettings(settings: AskUserSettings): void {
+  const file = readSettingsFile();
+
+  if (!isRecord(file[SETTINGS_KEY])) {
+    file[SETTINGS_KEY] = {};
+  }
+
+  (file[SETTINGS_KEY] as Record<string, unknown>).askUser = {
+    enabled: settings.enabled,
+    allowedFormats: settings.allowedFormats,
+  };
+
+  writeSettingsFile(file);
+  cachedSettings = settings;
+}
+
+/**
+ * Clear cached settings (for testing or reload).
+ */
+export function clearSettingsCache(): void {
+  cachedSettings = null;
+}

package/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @pi-unipi/ask-user — Extension entry
+ *
+ * Provides ask_user tool for structured user input with single-select,
+ * multi-select, and freeform modes. Includes bundled skill for agent guidance.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  ASK_USER_TOOLS,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+import { registerAskUserTools } from "./tools.js";
+import { registerAskUserCommands } from "./commands.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+export default function (pi: ExtensionAPI) {
+  // Register skills directory
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+  pi.on("resources_discover", async () => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register tools and commands
+  registerAskUserTools(pi);
+  registerAskUserCommands(pi);
+
+  // Session lifecycle — announce module
+  pi.on("session_start", async () => {
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.ASK_USER,
+      version: VERSION,
+      commands: ["unipi:ask-user-settings"],
+      tools: [ASK_USER_TOOLS.ASK],
+    });
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pi-unipi/ask-user",
+  "version": "0.1.1",
+  "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/ask-user"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "ask-user",
+    "interactive",
+    "user-input"
+  ],
+  "files": [
+    "index.ts",
+    "types.ts",
+    "tools.ts",
+    "ask-ui.ts",
+    "commands.ts",
+    "config.ts",
+    "settings-tui.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/settings-tui.ts

@@ -0,0 +1,164 @@
+/**
+ * @pi-unipi/ask-user — Settings TUI Component
+ *
+ * Interactive settings editor for ask_user tool.
+ * Allows enabling/disabling the tool and configuring allowed question formats.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { truncateToWidth } from "@mariozechner/pi-tui";
+import { getAskUserSettings, saveAskUserSettings, type AskUserSettings } from "./config.js";
+
+/** ANSI escape codes */
+const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  // Colors
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+/** Toggle symbols */
+const TOGGLE_ON = `${ansi.green}●${ansi.reset}`;
+const TOGGLE_OFF = `${ansi.dim}○${ansi.reset}`;
+
+/** Setting items */
+interface SettingItem {
+  key: string;
+  label: string;
+  description: string;
+  getValue: (settings: AskUserSettings) => boolean;
+  setValue: (settings: AskUserSettings, value: boolean) => void;
+}
+
+/** List of configurable settings */
+const SETTINGS: SettingItem[] = [
+  {
+    key: "enabled",
+    label: "Enable ask_user tool",
+    description: "Allow the agent to ask structured questions",
+    getValue: (s) => s.enabled,
+    setValue: (s, v) => (s.enabled = v),
+  },
+  {
+    key: "singleSelect",
+    label: "Allow single-select",
+    description: "Questions with one correct answer",
+    getValue: (s) => s.allowedFormats.singleSelect,
+    setValue: (s, v) => (s.allowedFormats.singleSelect = v),
+  },
+  {
+    key: "multiSelect",
+    label: "Allow multi-select",
+    description: "Questions with multiple correct answers",
+    getValue: (s) => s.allowedFormats.multiSelect,
+    setValue: (s, v) => (s.allowedFormats.multiSelect = v),
+  },
+  {
+    key: "freeform",
+    label: "Allow freeform text",
+    description: "Open-ended questions with text input",
+    getValue: (s) => s.allowedFormats.freeform,
+    setValue: (s, v) => (s.allowedFormats.freeform = v),
+  },
+];
+
+/**
+ * Settings overlay component.
+ */
+export class AskUserSettingsOverlay implements Component {
+  private settings: AskUserSettings;
+  private selectedIndex = 0;
+  /** Callback when overlay should close */
+  onClose?: () => void;
+
+  constructor() {
+    this.settings = getAskUserSettings();
+  }
+
+  /**
+   * Invalidate cached render state.
+   */
+  invalidate(): void {
+    // No cached state
+  }
+
+  /**
+   * Handle keyboard input.
+   */
+  handleInput(data: string): void {
+    switch (data) {
+      case "\x1b[A": // Up
+      case "k":
+        this.selectedIndex = (this.selectedIndex - 1 + SETTINGS.length) % SETTINGS.length;
+        break;
+      case "\x1b[B": // Down
+      case "j":
+        this.selectedIndex = (this.selectedIndex + 1) % SETTINGS.length;
+        break;
+      case " ": // Space - toggle
+        this.toggleSetting(SETTINGS[this.selectedIndex].key);
+        break;
+      case "\r": // Enter - save and close
+        this.save();
+        this.onClose?.();
+        break;
+      case "\x1b": // Escape - close without saving
+        this.onClose?.();
+        break;
+    }
+  }
+
+  /**
+   * Toggle a setting by key.
+   */
+  private toggleSetting(key: string): void {
+    const item = SETTINGS.find((s) => s.key === key);
+    if (!item) return;
+    const current = item.getValue(this.settings);
+    item.setValue(this.settings, !current);
+  }
+
+  /**
+   * Save settings to disk.
+   */
+  private save(): void {
+    saveAskUserSettings(this.settings);
+  }
+
+  /**
+   * Render the overlay.
+   */
+  render(width: number): string[] {
+    const lines: string[] = [];
+    const add = (s: string) => lines.push(truncateToWidth(s, width));
+
+    // Header
+    add(`${ansi.bold}${ansi.cyan}Ask User Settings${ansi.reset}`);
+    add(`${ansi.dim}Configure how the agent can ask you questions${ansi.reset}`);
+    add("");
+
+    // Settings list
+    for (let i = 0; i < SETTINGS.length; i++) {
+      const item = SETTINGS[i];
+      const isSelected = i === this.selectedIndex;
+      const value = item.getValue(this.settings);
+      const toggle = value ? TOGGLE_ON : TOGGLE_OFF;
+      const labelColor = isSelected ? ansi.bold : ansi.dim;
+      const descColor = ansi.gray;
+
+      add(`${isSelected ? ansi.cyan + "▸" + ansi.reset : " "} ${toggle} ${labelColor}${item.label}${ansi.reset}`);
+      add(`   ${descColor}${item.description}${ansi.reset}`);
+    }
+
+    // Footer
+    add("");
+    add(`${ansi.dim}↑↓ navigate • Space toggle • Enter save • Esc cancel${ansi.reset}`);
+
+    return lines;
+  }
+}

package/skills/ask-user/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ask-user
+description: >
+  Interactive decision-gating tool for structured user input.
+  Use ask_user when you need user confirmation, preferences, or decisions
+  before proceeding with high-impact or ambiguous choices.
+allowed-tools:
+  - ask_user
+---
+
+# Ask User
+
+Use the `ask_user` tool to collect structured input from the user.
+
+## When to use ask_user
+
+- Architectural trade-offs with high impact
+- Requirements are ambiguous or conflicting
+- Assumptions would materially change implementation
+- User preferences needed (style, approach, priority)
+- Confirming before destructive operations
+
+## Decision Handshake Flow
+
+1. Gather evidence and summarize context
+2. Ask ONE focused question via `ask_user`
+3. Wait for explicit user choice
+4. Confirm the decision, then proceed
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `question` | string | required | The question to ask |
+| `context` | string? | — | Additional context shown before question |
+| `options` | array? | [] | Multiple-choice options with labels, descriptions, values |
+| `allowMultiple` | boolean? | false | Enable multi-select |
+| `allowFreeform` | boolean? | true | Add "Custom response" checkable option |
+| `timeout` | number? | — | Auto-dismiss after N ms |
+
+## Examples
+
+Single choice:
+```
+ask_user({
+  question: "Which database should we use?",
+  options: [
+    { label: "PostgreSQL", description: "Reliable, feature-rich" },
+    { label: "SQLite", description: "Simple, serverless" }
+  ]
+})
+```
+
+Multi-select:
+```
+ask_user({
+  question: "Which features to implement?",
+  options: [
+    { label: "Auth", value: "auth" },
+    { label: "Cache", value: "cache" },
+    { label: "Logging", value: "logging" }
+  ],
+  allowMultiple: true
+})
+```
+
+With context:
+```
+ask_user({
+  question: "Which approach?",
+  context: "Current bottleneck: network I/O. Goal: reduce latency.",
+  options: [
+    { label: "Cache-first" },
+    { label: "DB-first" }
+  ]
+})
+```
+
+Freeform only:
+```
+ask_user({
+  question: "What should we name this module?",
+  options: [],
+  allowFreeform: true
+})
+```
+
+Combined (multi-select + freeform):
+```
+ask_user({
+  question: "Which features and what custom feature?",
+  options: [
+    { label: "Auth", value: "auth" },
+    { label: "Cache", value: "cache" }
+  ],
+  allowMultiple: true,
+  allowFreeform: true
+})
+```
+User can check "Auth", "Cache", and "Custom response" to type additional features.