@hobin/developer 0.1.5 → 0.1.6

package/extensions/tui.ts

@@ -1,8 +1,9 @@
-import {
-  type ExtensionCommandContext,
-  type KeybindingsManager,
-  type Theme,
-  type ThemeColor,
+import type {
+  ExtensionCommandContext,
+  ExtensionContext,
+  KeybindingsManager,
+  Theme,
+  ThemeColor,
 } from "@earendil-works/pi-coding-agent";
 import {
   Container,
@@ -17,6 +18,8 @@ import {
 
 import {
   protocolState,
+  type ChoiceResponseField,
+  type ChoiceResponseOption,
   type DeveloperMode,
   type DeveloperState,
   type JudgmentStatus,
@@ -24,7 +27,9 @@ import {
   type ProtocolState,
 } from "./state.ts";
 
-export type DeveloperAction = "status" | "questions" | DeveloperMode;
+export type DeveloperAction =
+  | { kind: "command"; value: "status" | "questions" | DeveloperMode }
+  | { kind: "question"; questionId: string };
 
 function modeName(mode: DeveloperMode): string {
   if (mode === "on") return "adaptive";
@@ -38,7 +43,8 @@ function protocolColor(value: ProtocolState): ThemeColor {
     value === "needs-answer" ||
     value === "needs-routing" ||
     value === "needs-verification"
-  ) return "warning";
+  )
+    return "warning";
   if (value === "needs-judgment") return "accent";
   return "dim";
 }
@@ -87,13 +93,7 @@ export function developerActionItems(state: DeveloperState): SelectItem[] {
       description: `${modeName(state.mode)} · ${currentProtocol} · ${state.pendingQuestions.length} open`,
     },
   ];
-  if (state.pendingQuestions.length > 0) {
-    items.push({
-      value: "questions",
-      label: "Revisit an open question",
-      description: `Choose from ${state.pendingQuestions.length} unresolved question(s) and prepare the editor`,
-    });
-  }
+  items.push(...pendingQuestionItems(state.pendingQuestions));
   items.push(
     {
       value: "on",
@@ -127,9 +127,13 @@ function resolutionRequestLabel(owner: PendingQuestion["resolutionOwner"]): stri
   return "Evidence or investigation request for Pi:";
 }
 
+const MAX_IMMEDIATE_REQUEST_BYTES = 16_000;
+const MAX_IMMEDIATE_REQUEST_LINES = 1_000;
 const ENABLE_MOUSE_SCROLL = "\u001b[?1000h\u001b[?1006h";
 const DISABLE_MOUSE_SCROLL = "\u001b[?1006l\u001b[?1000l";
 
+export type ImmediateQuestionDisposition = { kind: "answer"; request: string } | { kind: "defer" };
+
 interface WritableTerminal {
   write(data: string): void;
 }
@@ -175,13 +179,19 @@ interface SelectDialogOptions {
   selectedDescriptionMaxLines: number;
 }
 
-function boundedWrappedLines(content: string, width: number, maxLines: number, ellipsis: string): string[] {
+function boundedWrappedLines(
+  content: string,
+  width: number,
+  maxLines: number,
+  ellipsis: string,
+): string[] {
   const contentWidth = Math.max(1, width);
   const wrapped = wrapTextWithAnsi(content, contentWidth);
   const visible = wrapped.slice(0, Math.max(1, maxLines));
   if (wrapped.length > visible.length && visible.length > 0) {
     const last = visible.length - 1;
-    visible[last] = truncateToWidth(visible[last] ?? "", Math.max(1, contentWidth - 1), "") + ellipsis;
+    visible[last] =
+      truncateToWidth(visible[last] ?? "", Math.max(1, contentWidth - 1), "") + ellipsis;
   }
   return visible;
 }
@@ -237,7 +247,10 @@ class WrappedSelectList {
     const lines: string[] = [];
     const startIndex = Math.max(
       0,
-      Math.min(this.selectedIndex - Math.floor(this.maxVisible / 2), this.items.length - this.maxVisible),
+      Math.min(
+        this.selectedIndex - Math.floor(this.maxVisible / 2),
+        this.items.length - this.maxVisible,
+      ),
     );
     const endIndex = Math.min(startIndex + this.maxVisible, this.items.length);
 
@@ -273,7 +286,11 @@ class WrappedSelectList {
       lines.push(
         this.theme.fg(
           "dim",
-          truncateToWidth(`  (${this.selectedIndex + 1}/${this.items.length})`, Math.max(1, width - 2), ""),
+          truncateToWidth(
+            `  (${this.selectedIndex + 1}/${this.items.length})`,
+            Math.max(1, width - 2),
+            "",
+          ),
         ),
       );
     }
@@ -287,9 +304,11 @@ class WrappedSelectList {
     if (wheelDirection !== undefined) {
       this.moveSelection(wheelDirection * 3);
     } else if (this.keybindings.matches(data, "tui.select.up")) {
-      this.selectedIndex = this.selectedIndex === 0 ? this.items.length - 1 : this.selectedIndex - 1;
+      this.selectedIndex =
+        this.selectedIndex === 0 ? this.items.length - 1 : this.selectedIndex - 1;
     } else if (this.keybindings.matches(data, "tui.select.down")) {
-      this.selectedIndex = this.selectedIndex === this.items.length - 1 ? 0 : this.selectedIndex + 1;
+      this.selectedIndex =
+        this.selectedIndex === this.items.length - 1 ? 0 : this.selectedIndex + 1;
     } else if (this.keybindings.matches(data, "tui.select.pageUp")) {
       this.moveSelection(-Math.max(1, this.maxVisible - 1));
     } else if (this.keybindings.matches(data, "tui.select.pageDown")) {
@@ -314,7 +333,7 @@ class WrappedSelectList {
 }
 
 async function showSelectDialog(
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
   options: SelectDialogOptions,
 ): Promise<string | undefined> {
   let mouseTerminal: WritableTerminal | undefined;
@@ -329,7 +348,9 @@ async function showSelectDialog(
         const updateText = () => {
           title.setText(theme.fg("accent", theme.bold(`◆ ${options.title}`)));
           subtitle.setText(theme.fg("muted", options.subtitle));
-          hint.setText(theme.fg("dim", "wheel/↑↓ · PgUp/PgDn · Home/End · enter select · esc cancel"));
+          hint.setText(
+            theme.fg("dim", "wheel/↑↓ · PgUp/PgDn · Home/End · enter select · esc cancel"),
+          );
         };
         updateText();
 
@@ -396,8 +417,18 @@ export async function showDeveloperActionSelector(
     selectedLabelMaxLines: 3,
     selectedDescriptionMaxLines: 3,
   });
-  if (result === "status" || result === "questions" || result === "on" || result === "strict" || result === "off") {
-    return result;
+  if (!result) return undefined;
+  if (
+    result === "status" ||
+    result === "questions" ||
+    result === "on" ||
+    result === "strict" ||
+    result === "off"
+  ) {
+    return { kind: "command", value: result };
+  }
+  if (state.pendingQuestions.some((question) => question.id === result)) {
+    return { kind: "question", questionId: result };
   }
   return undefined;
 }
@@ -409,7 +440,8 @@ export function showPendingQuestionSelector(
   if (questions.length === 0) return Promise.resolve(undefined);
   return showSelectDialog(ctx, {
     title: "Resolve an open Developer question",
-    subtitle: "Enter opens an answer/evidence editor; the question closes after a resolved or not-applicable judgment",
+    subtitle:
+      "Enter opens an answer/evidence editor; the question closes after a resolved or not-applicable judgment",
     items: pendingQuestionItems(questions),
     width: "92%",
     minWidth: 88,
@@ -419,6 +451,240 @@ export function showPendingQuestionSelector(
   });
 }
 
+interface ChoiceResponseAnswer {
+  option: ChoiceResponseOption;
+  detail?: string;
+}
+
+function responseWithinLimits(
+  ctx: ExtensionContext,
+  request: string,
+  label = "Question response",
+): boolean {
+  const requestBytes = new TextEncoder().encode(request).byteLength;
+  const requestLines = request.split(/\r?\n/).length;
+  if (requestBytes <= MAX_IMMEDIATE_REQUEST_BYTES && requestLines <= MAX_IMMEDIATE_REQUEST_LINES) {
+    return true;
+  }
+  ctx.ui.notify(
+    `${label} is too large (${requestBytes} bytes, ${requestLines} lines); shorten it before submitting.`,
+    "warning",
+  );
+  return false;
+}
+
+function choiceDetailInitial(field: ChoiceResponseField, option: ChoiceResponseOption): string {
+  return [
+    `Decision: ${field.prompt}`,
+    `Selected: ${option.value} — ${option.label}`,
+    "",
+    option.detailPrompt,
+    "",
+    "Required detail:",
+  ].join("\n");
+}
+
+async function editChoiceDetail(
+  ctx: ExtensionContext,
+  field: ChoiceResponseField,
+  option: ChoiceResponseOption,
+): Promise<string | undefined> {
+  const initial = choiceDetailInitial(field, option);
+  while (true) {
+    const response = await ctx.ui.editor(`Add detail for ${field.id} · ${option.value}`, initial);
+    if (response === undefined) return undefined;
+    const detail = (
+      response.startsWith(initial) ? response.slice(initial.length) : response
+    ).trim();
+    if (!detail) {
+      ctx.ui.notify("This choice requires a non-empty detail.", "warning");
+      continue;
+    }
+    if (!responseWithinLimits(ctx, detail, "Choice detail")) continue;
+    return detail;
+  }
+}
+
+function structuredResolutionRequest(
+  question: PendingQuestion,
+  answers: ReadonlyArray<ChoiceResponseAnswer | undefined>,
+): string {
+  const fields = question.responseSpec?.fields ?? [];
+  const lines = [questionResolutionPrompt(question), "", "Structured answer:"];
+  for (const [index, field] of fields.entries()) {
+    const answer = answers[index];
+    if (!answer) continue;
+    lines.push(`- ${field.id}: ${answer.option.value} — ${answer.option.label}`);
+    if (answer.detail) lines.push(`  Detail: ${answer.detail}`);
+  }
+  return lines.join("\n");
+}
+
+type ChoiceFieldAction =
+  | { kind: "answer"; answer: ChoiceResponseAnswer }
+  | { kind: "cancel" }
+  | { kind: "retry" };
+
+type ChoiceReviewAction =
+  | { kind: "submit" }
+  | { kind: "edit"; fieldIndex: number }
+  | { kind: "back" };
+
+async function selectChoiceAnswer(
+  ctx: ExtensionContext,
+  field: ChoiceResponseField,
+  fieldIndex: number,
+  fieldCount: number,
+): Promise<ChoiceFieldAction> {
+  const selectedValue = await showSelectDialog(ctx, {
+    title: `Decision ${fieldIndex + 1}/${fieldCount} · ${field.id}`,
+    subtitle: field.description ?? field.prompt,
+    items: field.options.map((option) => ({
+      value: option.value,
+      label: `${option.value} · ${option.label}`,
+      description: option.description ?? field.prompt,
+    })),
+    width: "92%",
+    minWidth: 88,
+    maxVisible: Math.min(field.options.length, 12),
+    selectedLabelMaxLines: 3,
+    selectedDescriptionMaxLines: 4,
+  });
+  if (!selectedValue) return { kind: "cancel" };
+  const option = field.options.find((candidate) => candidate.value === selectedValue);
+  if (!option) return { kind: "retry" };
+  const detail = option.detailPrompt ? await editChoiceDetail(ctx, field, option) : undefined;
+  if (option.detailPrompt && detail === undefined) return { kind: "retry" };
+  return { kind: "answer", answer: { option, detail } };
+}
+
+async function reviewChoiceAnswers(
+  ctx: ExtensionContext,
+  question: PendingQuestion,
+  fields: ChoiceResponseField[],
+  answers: ReadonlyArray<ChoiceResponseAnswer | undefined>,
+): Promise<ChoiceReviewAction> {
+  const action = await showSelectDialog(ctx, {
+    title: "Review structured answer",
+    subtitle: question.question,
+    items: [
+      {
+        value: "submit",
+        label: "Submit answers",
+        description: "Send these decisions to Pi; the question remains open until judgment",
+      },
+      ...fields.map((field, index) => {
+        const answer = answers[index];
+        return {
+          value: `edit:${index}`,
+          label: `${field.id} · ${answer?.option.value ?? "missing"} — ${answer?.option.label ?? "Missing answer"}`,
+          description: answer?.detail ? `Detail: ${answer.detail}` : "Enter to change this answer",
+        };
+      }),
+    ],
+    width: "92%",
+    minWidth: 88,
+    maxVisible: Math.min(fields.length + 1, 12),
+    selectedLabelMaxLines: 3,
+    selectedDescriptionMaxLines: 4,
+  });
+  if (action === "submit") return { kind: "submit" };
+  if (!action?.startsWith("edit:")) return { kind: "back" };
+  const fieldIndex = Number(action.slice("edit:".length));
+  if (!Number.isInteger(fieldIndex) || fieldIndex < 0 || fieldIndex >= fields.length) {
+    return { kind: "back" };
+  }
+  return { kind: "edit", fieldIndex };
+}
+
+function previousChoiceField(
+  fieldIndex: number,
+  fieldCount: number,
+  returnToReview: boolean,
+): number | undefined {
+  if (returnToReview) return fieldCount;
+  return fieldIndex === 0 ? undefined : fieldIndex - 1;
+}
+
+async function collectChoiceResponse(
+  ctx: ExtensionContext,
+  question: PendingQuestion,
+): Promise<string | undefined> {
+  const fields = question.responseSpec?.fields;
+  if (!fields || fields.length === 0) return undefined;
+  const answers: Array<ChoiceResponseAnswer | undefined> = [];
+  let fieldIndex = 0;
+  let returnToReview = false;
+
+  while (true) {
+    if (fieldIndex < fields.length) {
+      const field = fields[fieldIndex];
+      if (!field) return undefined;
+      const action = await selectChoiceAnswer(ctx, field, fieldIndex, fields.length);
+      if (action.kind === "retry") continue;
+      if (action.kind === "cancel") {
+        fieldIndex = previousChoiceField(fieldIndex, fields.length, returnToReview) ?? -1;
+      }
+      if (fieldIndex < 0) return undefined;
+      if (action.kind === "cancel") continue;
+      answers[fieldIndex] = action.answer;
+      fieldIndex = returnToReview ? fields.length : fieldIndex + 1;
+      continue;
+    }
+
+    const action = await reviewChoiceAnswers(ctx, question, fields, answers);
+    if (action.kind === "submit") return structuredResolutionRequest(question, answers);
+    if (action.kind === "edit") {
+      fieldIndex = action.fieldIndex;
+      returnToReview = true;
+      continue;
+    }
+    returnToReview = false;
+    fieldIndex = fields.length - 1;
+  }
+}
+
+export async function promptImmediateUserQuestion(
+  ctx: ExtensionContext,
+  question: PendingQuestion,
+): Promise<ImmediateQuestionDisposition> {
+  while (true) {
+    const action = await showSelectDialog(ctx, {
+      title: "Developer needs a decision",
+      subtitle: question.question,
+      items: [
+        {
+          value: "answer",
+          label: "Answer now",
+          description:
+            "Review the full context and provide the decision required before direct work",
+        },
+        {
+          value: "defer",
+          label: "Leave open",
+          description: "Keep this question in Developer and answer it later",
+        },
+      ],
+      width: "92%",
+      minWidth: 88,
+      maxVisible: 2,
+      selectedLabelMaxLines: 3,
+      selectedDescriptionMaxLines: 3,
+    });
+    if (action !== "answer") return { kind: "defer" };
+
+    const request = question.responseSpec
+      ? await collectChoiceResponse(ctx, question)
+      : await ctx.ui.editor(
+          "Answer the new Developer question",
+          questionResolutionPrompt(question),
+        );
+    if (request === undefined) continue;
+    if (!responseWithinLimits(ctx, request)) continue;
+    return { kind: "answer", request };
+  }
+}
+
 export class DeveloperWidget {
   private readonly state: DeveloperState;
   private readonly theme: Theme;
@@ -450,10 +716,14 @@ export class DeveloperWidget {
       );
     }
     if (this.state.pendingQuestions.length > 3) {
-      lines.push(this.theme.fg("dim", `  +${this.state.pendingQuestions.length - 3} more open questions`));
+      lines.push(
+        this.theme.fg("dim", `  +${this.state.pendingQuestions.length - 3} more open questions`),
+      );
     }
     if (this.state.implementationFramingRequired) {
-      lines.push(this.theme.fg("warning", "→ next · sketch feature shape or signal structural movement"));
+      lines.push(
+        this.theme.fg("warning", "◇ gate · frame implementation before direct (sketch or signal)"),
+      );
     }
     if (this.state.rerouteRequired) {
       lines.push(this.theme.fg("warning", "→ next · reroute from the latest direct landing"));
@@ -527,8 +797,14 @@ export class DeveloperStatusPanel {
     const innerWidth = Math.max(1, panelWidth - 2);
     const rows: string[] = [];
     const border = (text: string) => this.theme.fg("borderAccent", text);
-    const row = (content = "") => `${border("│")}${truncateToWidth(content, innerWidth, "…", true)}${border("│")}`;
-    const addWrapped = (label: string, value: string, color: ThemeColor = "muted", maxLines = 2) => {
+    const row = (content = "") =>
+      `${border("│")}${truncateToWidth(content, innerWidth, "…", true)}${border("│")}`;
+    const addWrapped = (
+      label: string,
+      value: string,
+      color: ThemeColor = "muted",
+      maxLines = 2,
+    ) => {
       const labelText = `${label} ·`;
       const plainPrefix = `  ${labelText} `;
       const styledPrefix = `  ${this.theme.fg("dim", labelText)} `;
@@ -538,13 +814,15 @@ export class DeveloperStatusPanel {
       if (wrapped.length > visible.length && visible.length > 0) {
         const last = visible.length - 1;
         visible[last] =
-          truncateToWidth(visible[last] ?? "", Math.max(1, contentWidth - 1), "") + this.theme.fg("dim", "…");
+          truncateToWidth(visible[last] ?? "", Math.max(1, contentWidth - 1), "") +
+          this.theme.fg("dim", "…");
       }
       rows.push(row(styledPrefix + (visible[0] ?? "")));
       const hangingIndent = " ".repeat(visibleWidth(plainPrefix));
       for (const line of visible.slice(1)) rows.push(row(hangingIndent + line));
     };
-    const section = (title: string) => rows.push(row(`  ${this.theme.fg("accent", this.theme.bold(title))}`));
+    const section = (title: string) =>
+      rows.push(row(`  ${this.theme.fg("accent", this.theme.bold(title))}`));
 
     rows.push(border(`╭${"─".repeat(innerWidth)}╮`));
     rows.push(row(`  ${this.theme.fg("accent", this.theme.bold("◆ Developer status"))}`));
@@ -558,7 +836,8 @@ export class DeveloperStatusPanel {
       `protocol ${this.theme.fg(protocolColor(currentProtocol), currentProtocol)}` +
       this.theme.fg("dim", " · ") +
       `target ${this.theme.fg("muted", state.activeRoute?.owner ?? "none")}`;
-    for (const line of wrapTextWithAnsi(summary, Math.max(1, innerWidth - 2))) rows.push(row(`  ${line}`));
+    for (const line of wrapTextWithAnsi(summary, Math.max(1, innerWidth - 2)))
+      rows.push(row(`  ${line}`));
     rows.push(row());
 
     section("Active route");
@@ -587,7 +866,12 @@ export class DeveloperStatusPanel {
         addWrapped("resolves when", question.resolutionCriteria, "dim", 2);
       }
       if (state.pendingQuestions.length > 4) {
-        addWrapped("more", `${state.pendingQuestions.length - 4} additional open questions`, "dim", 1);
+        addWrapped(
+          "more",
+          `${state.pendingQuestions.length - 4} additional open questions`,
+          "dim",
+          1,
+        );
       }
     }
 
@@ -598,7 +882,9 @@ export class DeveloperStatusPanel {
     } else {
       const recentJudgments = state.judgmentHistory.slice(-10).toReversed();
       for (const judgment of recentJudgments) {
-        const route = state.routeHistory.find((candidate) => candidate.routeId === judgment.routeId);
+        const route = state.routeHistory.find(
+          (candidate) => candidate.routeId === judgment.routeId,
+        );
         addWrapped(
           `${judgment.owner} ${judgment.status}`,
           `${judgment.question} → ${judgmentSummary(judgment.result)}`,
@@ -610,11 +896,21 @@ export class DeveloperStatusPanel {
           addWrapped(`considered ${alternative.owner}`, alternative.reason, "dim", 2);
         }
         for (const update of judgment.questionUpdates ?? []) {
-          addWrapped(`question ${update.status}`, `${update.questionId} → ${update.result}`, "accent", 2);
+          addWrapped(
+            `question ${update.status}`,
+            `${update.questionId} → ${update.result}`,
+            "accent",
+            2,
+          );
         }
       }
       if (state.judgmentHistory.length > recentJudgments.length) {
-        addWrapped("earlier", `${state.judgmentHistory.length - recentJudgments.length} earlier judgments`, "dim", 1);
+        addWrapped(
+          "earlier",
+          `${state.judgmentHistory.length - recentJudgments.length} earlier judgments`,
+          "dim",
+          1,
+        );
       }
     }
 
@@ -656,7 +952,10 @@ export class DeveloperStatusPanel {
   }
 }
 
-export async function showDeveloperStatus(ctx: ExtensionCommandContext, view: DeveloperStatusView): Promise<void> {
+export async function showDeveloperStatus(
+  ctx: ExtensionCommandContext,
+  view: DeveloperStatusView,
+): Promise<void> {
   let mouseTerminal: WritableTerminal | undefined;
   try {
     await ctx.ui.custom<void>(
@@ -685,10 +984,14 @@ export async function showDeveloperStatus(ctx: ExtensionCommandContext, view: De
 
 export function questionResolutionPrompt(question: PendingQuestion): string {
   const requestLabel = resolutionRequestLabel(question.resolutionOwner);
+  const context = question.context
+    ? ["", "Decision or evidence context:", question.context, ""]
+    : [];
   return [
     "Resolve this open Developer question.",
     "",
     `Question: ${question.question}`,
+    ...context,
     `Resolution owner: ${question.resolutionOwner}`,
     `Gate: ${question.gate}`,
     `Resolution criteria: ${question.resolutionCriteria}`,
@@ -704,6 +1007,7 @@ export function editQuestionResolutionRequest(
   ctx: ExtensionCommandContext,
   question: PendingQuestion,
 ): Promise<string | undefined> {
+  if (question.responseSpec) return collectChoiceResponse(ctx, question);
   const current = ctx.ui.getEditorText();
   const request = questionResolutionPrompt(question);
   const initial = current.trim() ? `${current.trimEnd()}\n\n${request}` : request;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Adaptive product-development reasoning and evidence for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "developer", "skills"],