@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/ask-user/form.js

@@ -0,0 +1,250 @@
+import { Input, Key, matchesKey, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+const OWN_ANSWER = "Type my own answer";
+export class QuestionForm {
+  questions;
+  theme;
+  done;
+  requestRender;
+  options;
+  tab = 0;
+  cursor;
+  picked;
+  written = new Map();
+  notes = new Map();
+  answered = new Set();
+  mode = "choose";
+  input = new Input();
+  cache;
+  focusedValue = false;
+  constructor(questions, theme, done, requestRender = () => {}, options = {}) {
+    this.questions = questions;
+    this.theme = theme;
+    this.done = done;
+    this.requestRender = requestRender;
+    this.options = options;
+    this.cursor = questions.map(() => 0);
+    this.picked = questions.map(() => new Set());
+    this.input.onSubmit = (value) => this.submitInput(value);
+    this.input.onEscape = () => this.leaveInput();
+  }
+  get focused() {
+    return this.focusedValue;
+  }
+  set focused(value) {
+    this.focusedValue = value;
+    this.input.focused = value && this.mode !== "choose";
+  }
+  get many() {
+    return this.questions.length > 1;
+  }
+  get onSubmitTab() {
+    return this.many && this.tab === this.questions.length;
+  }
+  get ownAnswer() {
+    return this.options.ownAnswer !== false;
+  }
+  rows(index) {
+    return this.questions[index].options.length + (this.ownAnswer ? 1 : 0);
+  }
+  refresh() {
+    this.cache = undefined;
+    this.requestRender();
+  }
+  finish() {
+    const answers = this.questions.map((question, index) => {
+      const note = this.notes.get(index);
+      const text = this.written.get(index);
+      return {
+        header: question.header,
+        question: question.question,
+        selected:
+          text === undefined
+            ? [...this.picked[index]].sort((a, b) => a - b).map((at) => question.options[at].label)
+            : [],
+        ...(text === undefined ? {} : { text }),
+        ...(note ? { note } : {}),
+      };
+    });
+    this.done({ status: "answered", answers });
+  }
+  /** After a question is answered: the next unanswered question, the Submit tab, or done for a single question. */
+  advance() {
+    this.answered.add(this.tab);
+    if (!this.many) return this.finish();
+    const next = this.questions.findIndex((_, index) => !this.answered.has(index));
+    this.tab = next === -1 ? this.questions.length : next;
+    this.refresh();
+  }
+  submitInput(value) {
+    const text = value.trim();
+    if (this.mode === "own") {
+      if (!text) return;
+      this.written.set(this.tab, text);
+      this.picked[this.tab].clear();
+      this.leaveInput(false);
+      this.advance();
+      return;
+    }
+    if (text) this.notes.set(this.tab, text);
+    else this.notes.delete(this.tab);
+    this.leaveInput();
+  }
+  leaveInput(render = true) {
+    this.mode = "choose";
+    this.input.setValue("");
+    this.input.focused = false;
+    if (render) this.refresh();
+  }
+  enterInput(mode) {
+    this.mode = mode;
+    this.input.setValue(mode === "note" ? (this.notes.get(this.tab) ?? "") : (this.written.get(this.tab) ?? ""));
+    this.input.focused = this.focusedValue;
+    this.refresh();
+  }
+  handleInput(data) {
+    if (this.mode !== "choose") {
+      this.input.handleInput(data);
+      this.refresh();
+      return;
+    }
+    if (matchesKey(data, Key.escape)) return this.done({ status: "dismissed" });
+    if (this.many && (matchesKey(data, Key.tab) || matchesKey(data, Key.right))) {
+      this.tab = (this.tab + 1) % (this.questions.length + 1);
+      return this.refresh();
+    }
+    if (this.many && (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left))) {
+      this.tab = (this.tab + this.questions.length) % (this.questions.length + 1);
+      return this.refresh();
+    }
+    if (this.onSubmitTab) {
+      if (matchesKey(data, Key.enter) && this.answered.size === this.questions.length) this.finish();
+      return;
+    }
+    const question = this.questions[this.tab];
+    const at = this.cursor[this.tab];
+    const own = at === question.options.length;
+    if (matchesKey(data, Key.up)) {
+      this.cursor[this.tab] = Math.max(0, at - 1);
+      return this.refresh();
+    }
+    if (matchesKey(data, Key.down)) {
+      this.cursor[this.tab] = Math.min(this.rows(this.tab) - 1, at + 1);
+      return this.refresh();
+    }
+    if (data === "n" && this.options.notes !== false) return this.enterInput("note");
+    if (question.multiSelect && data === " " && !own) {
+      const picked = this.picked[this.tab];
+      if (picked.has(at)) picked.delete(at);
+      else picked.add(at);
+      this.written.delete(this.tab);
+      this.answered.delete(this.tab);
+      return this.refresh();
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (own) return this.enterInput("own");
+      const picked = this.picked[this.tab];
+      if (!question.multiSelect) {
+        picked.clear();
+        picked.add(at);
+      } else if (picked.size === 0) picked.add(at);
+      this.written.delete(this.tab);
+      this.advance();
+    }
+  }
+  invalidate() {
+    this.cache = undefined;
+  }
+  render(width) {
+    if (this.cache) return this.cache;
+    const t = this.theme;
+    const w = Math.max(1, width);
+    const lines = [];
+    const wrap = (prefix, text) => {
+      const indent = visibleWidth(prefix);
+      const body = wrapTextWithAnsi(text, Math.max(1, w - indent));
+      body.forEach((line, i) => lines.push(`${i === 0 ? prefix : " ".repeat(indent)}${line}`));
+    };
+    lines.push(t.fg("accent", "─".repeat(w)));
+    if (this.many) {
+      const tabs = this.questions.map((question, index) => {
+        const label = ` ${this.answered.has(index) ? "■" : "□"} ${question.header} `;
+        return index === this.tab
+          ? t.bold(t.fg("accent", label))
+          : t.fg(this.answered.has(index) ? "success" : "muted", label);
+      });
+      const ready = this.answered.size === this.questions.length;
+      const submit = " ✓ Submit ";
+      tabs.push(this.onSubmitTab ? t.bold(t.fg("accent", submit)) : t.fg(ready ? "success" : "dim", submit));
+      wrap(" ", tabs.join(" "));
+      lines.push("");
+    }
+    if (this.onSubmitTab) {
+      wrap(" ", t.bold("Your answers"));
+      lines.push("");
+      this.questions.forEach((question, index) => {
+        const text = this.written.get(index);
+        const chosen = [...this.picked[index]].map((at) => question.options[at].label).join(", ");
+        const answer =
+          text !== undefined ? `"${text}"` : this.answered.has(index) ? chosen : t.fg("warning", "not answered");
+        wrap(" ", `${t.fg("muted", `${question.header}:`)} ${answer}`);
+        const note = this.notes.get(index);
+        if (note) wrap("   ", t.fg("dim", `note: ${note}`));
+      });
+      lines.push("");
+      wrap(
+        " ",
+        this.answered.size === this.questions.length
+          ? t.fg("success", "Enter to submit")
+          : t.fg("warning", "Answer every question to submit"),
+      );
+    } else {
+      const index = this.tab;
+      const question = this.questions[index];
+      wrap(" ", `${t.fg("muted", `${question.header} ·`)} ${t.bold(question.question)}`);
+      lines.push("");
+      const rows = [...question.options, ...(this.ownAnswer ? [{ label: OWN_ANSWER }] : [])];
+      rows.forEach((option, at) => {
+        const own = at === question.options.length;
+        const here = at === this.cursor[index] && this.mode === "choose";
+        const mark = question.multiSelect && !own ? (this.picked[index].has(at) ? "[x] " : "[ ] ") : "";
+        const chosen = !question.multiSelect && !own && this.answered.has(index) && this.picked[index].has(at);
+        const label = `${at + 1}. ${mark}${option.label}${chosen ? " ✓" : ""}`;
+        wrap(here ? t.fg("accent", "› ") : "  ", here ? t.fg("accent", label) : label);
+        const description = own ? this.written.get(index) : option.description;
+        if (description) wrap("     ", t.fg("muted", own ? `"${description}"` : description));
+      });
+      const note = this.notes.get(index);
+      if (note && this.mode !== "note") {
+        lines.push("");
+        wrap(" ", t.fg("dim", `Note: ${note}`));
+      }
+      if (this.mode !== "choose") {
+        lines.push("");
+        wrap(" ", t.fg("muted", this.mode === "own" ? "Your answer:" : "Note for this question:"));
+        for (const line of this.input.render(Math.max(1, w - 2))) lines.push(` ${line}`);
+      }
+    }
+    lines.push("");
+    if (this.options.deadline !== undefined) {
+      const left = Math.max(0, Math.ceil((this.options.deadline - Date.now()) / 1000));
+      wrap(
+        " ",
+        t.fg("dim", `Closes in ${Math.floor(left / 60)}:${String(left % 60).padStart(2, "0")} without an answer`),
+      );
+    }
+    const help =
+      this.mode !== "choose"
+        ? "Enter to save · Esc to go back"
+        : [
+            "↑↓ move",
+            this.questions[this.tab]?.multiSelect ? "Space toggle · Enter confirm" : "Enter choose",
+            ...(this.options.notes !== false ? ["n note"] : []),
+            ...(this.many ? ["Tab next"] : []),
+            "Esc close without answering",
+          ].join(" · ");
+    wrap(" ", t.fg("dim", help));
+    lines.push(t.fg("accent", "─".repeat(w)));
+    this.cache = lines;
+    return lines;
+  }
+}

package/pi-extension/dist/ask-user/questions.js

@@ -0,0 +1,66 @@
+/*
+ * The questions ask_user puts to the user, and the answers it returns: Claude Code's AskUserQuestion shape (1-4
+ * questions, a short header each, 2-4 options with descriptions, multi-select), since models know it. Every question
+ * also accepts the user's own words and a note; the dialog adds those, the model never lists them.
+ */
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER = 12;
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+/** The questions as given, or the first reason they cannot be asked. */
+export function validateQuestions(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.length > MAX_QUESTIONS)
+    return { error: `Ask 1 to ${MAX_QUESTIONS} questions.` };
+  const questions = [];
+  const headers = new Set();
+  for (const [index, raw] of value.entries()) {
+    const at = `Question ${index + 1}`;
+    const question = text(raw?.question);
+    const header = text(raw?.header);
+    if (!question) return { error: `${at} has no question text.` };
+    if (!header || header.length > MAX_HEADER)
+      return { error: `${at} needs a header of 1 to ${MAX_HEADER} characters.` };
+    if (headers.has(header)) return { error: `${at} repeats the header "${header}".` };
+    headers.add(header);
+    const options = Array.isArray(raw?.options) ? raw.options : [];
+    if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS)
+      return { error: `${at} needs ${MIN_OPTIONS} to ${MAX_OPTIONS} options.` };
+    const labels = new Set();
+    const normalized = [];
+    for (const option of options) {
+      const label = text(option?.label);
+      if (!label) return { error: `${at} has an option with no label.` };
+      if (/^other\b/i.test(label))
+        return { error: `${at} lists "${label}": the dialog adds the user's own answer itself; remove it.` };
+      if (labels.has(label)) return { error: `${at} repeats the option "${label}".` };
+      labels.add(label);
+      const description = text(option?.description);
+      normalized.push(description ? { label, description } : { label });
+    }
+    questions.push({
+      question,
+      header,
+      options: normalized,
+      ...(raw?.multiSelect === true ? { multiSelect: true } : {}),
+    });
+  }
+  return { questions };
+}
+/** What the model reads after the dialog. */
+export function outcomeText(outcome) {
+  if (outcome.status === "unavailable") return `${outcome.reason} Ask in your reply and end your turn.`;
+  if (outcome.status === "dismissed")
+    return "The user closed the dialog without answering. Do not act on the choice: ask in your reply, or continue only with work that does not depend on it.";
+  const lines = ["The user answered in a dialog:"];
+  for (const answer of outcome.answers) {
+    lines.push(`- ${answer.header}: ${answer.question}`);
+    if (answer.text !== undefined) lines.push(`  Answer, in their words: ${answer.text}`);
+    else lines.push(`  Answer: ${answer.selected.join("; ")}`);
+    if (answer.note) lines.push(`  Note: ${answer.note}`);
+  }
+  lines.push(
+    "Each answer decides only its question. A note or written answer that asks something, sets a condition or asks for more information is not a decision: respond to it before acting.",
+  );
+  return lines.join("\n");
+}

package/pi-extension/dist/ask-user/tool.js

@@ -0,0 +1,124 @@
+import { Text } from "@earendil-works/pi-tui";
+import { firstLine, foldRow, paint } from "../host/rows.js";
+import { askUser } from "./ask.js";
+import { MAX_HEADER, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, outcomeText, validateQuestions } from "./questions.js";
+export const ASK_USER = "ask_user";
+const DESCRIPTION = [
+  "Ask the user in a dialog when a choice is theirs to make: what to do, which direction to take, whether to go beyond what they asked. The call waits for their answer.",
+  `Ask 1 to ${MAX_QUESTIONS} questions. Each has a full-sentence question, a header of at most ${MAX_HEADER} characters, and ${MIN_OPTIONS} to ${MAX_OPTIONS} options: a label of a few words and a description of what choosing it means. Put your recommended option first and end its label with "(Recommended)". Use multiSelect when the options are not exclusive. The dialog adds a field for the user's own answer and a note, so never list an "Other" option.`,
+  "Several questions in one call only when each is the user's and none depends on another's answer. Say any context the choice needs in your reply before calling: the dialog shows only the questions and options.",
+  "If the user closes the dialog or no one can answer it, the result says so: then ask in your reply.",
+].join("\n\n");
+// Pi adds a tool's guidelines to the system prompt's rules while the tool is active.
+const GUIDELINE =
+  "Use ask_user for a choice that is the user's to make, with the options that matter and your recommendation first; never for facts you can look up or work out.";
+const textOf = (result) =>
+  (result?.content ?? [])
+    .filter((part) => part?.type === "text")
+    .map((part) => part.text ?? "")
+    .join("\n");
+/** Registered once, declared only while Freeflow is effective outside subagents. */
+export function registerAskUserTool(pi, host) {
+  pi.registerTool({
+    name: ASK_USER,
+    label: "Question",
+    description: DESCRIPTION,
+    promptGuidelines: [GUIDELINE],
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        questions: {
+          type: "array",
+          minItems: 1,
+          maxItems: MAX_QUESTIONS,
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              question: { type: "string", description: "The full question, ending with a question mark." },
+              header: {
+                type: "string",
+                description: `A label of at most ${MAX_HEADER} characters, such as "Default".`,
+              },
+              options: {
+                type: "array",
+                minItems: MIN_OPTIONS,
+                maxItems: MAX_OPTIONS,
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  properties: {
+                    label: { type: "string", description: "A few words; the recommended one first." },
+                    description: { type: "string", description: "What choosing it means, and its tradeoff." },
+                  },
+                  required: ["label", "description"],
+                },
+              },
+              multiSelect: { type: "boolean", description: "True when the user may choose more than one." },
+            },
+            required: ["question", "header", "options"],
+          },
+        },
+      },
+      required: ["questions"],
+    },
+    // It asks the user, so scripts must not call it, and its transcript views apply (see task_memory).
+    exposure: "model-only",
+    defaultActive: false,
+    executionMode: "sequential",
+    // One line each for what was asked and what the user answered; options and notes when expanded or short.
+    renderCall: (args, theme, context) => {
+      const questions = (Array.isArray(args?.questions) ? args.questions : []).filter((q) => q?.question);
+      const title = paint(theme, "toolTitle", "Question");
+      if (!questions.length) return new Text(title, 0, 0);
+      const head =
+        questions.length === 1
+          ? `${title} · ${paint(theme, "accent", String(questions[0].header ?? ""))}: ${firstLine(questions[0].question, 120)}`
+          : `${title} · ${questions.map((q) => paint(theme, "accent", String(q.header ?? ""))).join(", ")}`;
+      const body = questions.flatMap((q) => [
+        ...(questions.length > 1 ? [`${q.header}: ${q.question}`] : q.question.length > 120 ? [q.question] : []),
+        ...(Array.isArray(q.options) ? q.options : []).map(
+          (o) => `${questions.length > 1 ? "  " : ""}- ${o.label}${o.description ? ` — ${o.description}` : ""}`,
+        ),
+      ]);
+      return foldRow(head, context?.expanded === true ? body : [], context?.expanded === true, theme);
+    },
+    renderResult: (result, options, theme) => {
+      const outcome = result?.details?.outcome;
+      if (outcome?.status === "answered") {
+        const lines = outcome.answers.map(
+          (answer) =>
+            `${answer.header}: ${answer.text !== undefined ? `"${answer.text}"` : answer.selected.join(", ")}${answer.note ? ` (note: ${answer.note})` : ""}`,
+        );
+        const head = paint(theme, "success", lines.length === 1 ? `Answered · ${lines[0]}` : "Answered");
+        return foldRow(head, lines.length === 1 ? [] : lines, options?.expanded === true, theme);
+      }
+      if (outcome?.status === "dismissed")
+        return new Text(paint(theme, "warning", "Closed without answering (Esc)"), 0, 0);
+      return new Text(paint(theme, "warning", firstLine(textOf(result)) || "Not asked"), 0, 0);
+    },
+    async execute(_id, params, signal, _update, ctx) {
+      const refused = host.refusal(ctx);
+      const checked = validateQuestions(params?.questions);
+      let outcome;
+      if (refused) outcome = { status: "unavailable", reason: refused };
+      else if ("error" in checked)
+        return { content: [{ type: "text", text: checked.error }], details: {}, isError: true };
+      else outcome = await askUser(ctx, checked.questions, signal);
+      return {
+        content: [{ type: "text", text: refused ? refused : outcomeText(outcome) }],
+        details: { outcome },
+        ...(outcome.status === "answered" ? {} : { isError: true }),
+      };
+    },
+  });
+}
+/** Declare or withdraw ask_user, keeping other tools in place. */
+export function applyAskUserTool(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(ASK_USER);
+  if (effective && !present) pi.setActiveTools([...current, ASK_USER]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== ASK_USER));
+}