@narumitw/pi-plan-mode 0.59.6 → 0.60.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,174 @@
1
+ import type { KeybindingHints, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
2
+ import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
3
+ import { hardWrapTerminalDocument, sanitizeTerminalDocument } from "@narumitw/pi-tui-kit/terminal-document";
4
+ import { sanitizeTerminalText } from "@narumitw/pi-tui-kit/terminal-text";
5
+ import type { PlanModeQuestionAnswer } from "./question-tool.js";
6
+
7
+ type QuestionResult = {
8
+ content: Array<{ type: string; text?: string }>;
9
+ details?: unknown;
10
+ };
11
+
12
+ type RenderContext = Partial<KeybindingHints> & { isError?: boolean };
13
+ type Answer = Pick<PlanModeQuestionAnswer, "header" | "question" | "answer" | "wasCustom" | "note">;
14
+ type Style = (text: string) => string;
15
+
16
+ const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
17
+
18
+ export function renderPlanModeQuestionCall(args: unknown, theme: Theme): Component {
19
+ const questions = isRecord(args) && Array.isArray(args.questions) ? args.questions : [];
20
+ return boundedComponent((width) => {
21
+ const title = questions.length > 1 ? "Plan questions" : "Plan question";
22
+ const headers = questions
23
+ .map((question) => (isRecord(question) ? displayLine(question.header) : ""))
24
+ .filter(Boolean);
25
+ const text =
26
+ theme.fg("toolTitle", theme.bold(title)) + theme.fg("muted", headers.length ? ` ${headers.join(" · ")}` : "");
27
+ return [truncateToWidth(text, width, "…")];
28
+ });
29
+ }
30
+
31
+ export function renderPlanModeQuestionResult(
32
+ result: QuestionResult,
33
+ { expanded, isPartial }: ToolRenderResultOptions,
34
+ theme: Theme,
35
+ context: RenderContext = {},
36
+ ): Component {
37
+ const text = result.content
38
+ .filter((block) => block.type === "text" && typeof block.text === "string")
39
+ .map((block) => block.text)
40
+ .join("\n");
41
+ const payload = questionPayload(result.details, text);
42
+
43
+ return boundedComponent((width) => {
44
+ const muted = (value: string) => theme.fg("muted", value);
45
+ const hint = () =>
46
+ context.keyText?.("app.tools.expand") && context.keyHint
47
+ ? [truncateToWidth(muted(context.keyHint("app.tools.expand", "to expand")), width, "…")]
48
+ : [];
49
+
50
+ if (isPartial) return [truncateToWidth(muted("Waiting for answers…"), width, "…")];
51
+
52
+ if (context.isError || payload?.cancelled === true) {
53
+ const reason = payload?.reason;
54
+ const failed = context.isError || reason === "invalid_input";
55
+ const status = context.isError
56
+ ? "Question failed"
57
+ : reason === "ui_unavailable"
58
+ ? "Interactive UI unavailable"
59
+ : reason === "plan_mode_inactive"
60
+ ? "Plan mode inactive"
61
+ : reason === "invalid_input"
62
+ ? "Invalid question"
63
+ : "Question cancelled";
64
+ const message = typeof payload?.message === "string" ? payload.message : text;
65
+ const lines = documentLines(status, width, (value) => theme.fg(failed ? "error" : "warning", value));
66
+ if (expanded) {
67
+ lines.push(...documentLines(message, width, muted, " "));
68
+ } else if (message) {
69
+ lines.push(...hint());
70
+ }
71
+ return lines;
72
+ }
73
+
74
+ const answers = payload?.answers;
75
+ if (payload?.cancelled === false && Array.isArray(answers) && answers.length > 0 && answers.every(isAnswer)) {
76
+ const lines: string[] = [];
77
+ for (const answer of answers) {
78
+ if (!expanded) {
79
+ const badge = answer.wasCustom ? muted(" (custom)") : "";
80
+ const note = answer.note ? muted(" · note") : "";
81
+ lines.push(
82
+ truncateToWidth(
83
+ theme.fg("success", "✓ ") +
84
+ muted(`${displayLine(answer.header)}: `) +
85
+ theme.fg("accent", displayLine(answer.answer)) +
86
+ badge +
87
+ note,
88
+ width,
89
+ "…",
90
+ ),
91
+ );
92
+ continue;
93
+ }
94
+ if (lines.length) lines.push("");
95
+ lines.push(...documentLines(answer.header, width, (value) => theme.fg("accent", theme.bold(value))));
96
+ lines.push(...documentLines(answer.question, width, muted, " "));
97
+ if (answer.wasCustom) lines.push(...documentLines("Custom answer", width, muted, " "));
98
+ lines.push(
99
+ ...documentLines(
100
+ answer.answer,
101
+ width,
102
+ (value) => theme.fg("text", value),
103
+ " ✓ ",
104
+ (value) => theme.fg("success", value),
105
+ ),
106
+ );
107
+ if (answer.note) {
108
+ lines.push(...documentLines("Note", width, muted, " "));
109
+ lines.push(...documentLines(answer.note, width, muted, " "));
110
+ }
111
+ }
112
+ if (!expanded) lines.push(...hint());
113
+ return lines;
114
+ }
115
+
116
+ const lines = documentLines(text || "No answer returned.", width, (value) => theme.fg("toolOutput", value));
117
+ return expanded || lines.length <= 4 ? lines : [...lines.slice(0, 4), ...hint()];
118
+ });
119
+ }
120
+
121
+ function questionPayload(details: unknown, text: string): Record<string, unknown> | undefined {
122
+ let payload: unknown;
123
+ try {
124
+ payload = JSON.parse(text);
125
+ } catch {
126
+ // Pi-generated errors and third-party tool-result hooks can return plain text.
127
+ }
128
+ const parsed = isRecord(payload) ? payload : undefined;
129
+ return isRecord(details) && typeof details.cancelled === "boolean" ? { ...parsed, ...details } : parsed;
130
+ }
131
+
132
+ function isAnswer(value: unknown): value is Answer {
133
+ return (
134
+ isRecord(value) &&
135
+ typeof value.header === "string" &&
136
+ typeof value.question === "string" &&
137
+ typeof value.answer === "string" &&
138
+ typeof value.wasCustom === "boolean" &&
139
+ (value.note === undefined || typeof value.note === "string")
140
+ );
141
+ }
142
+
143
+ function isRecord(value: unknown): value is Record<string, unknown> {
144
+ return typeof value === "object" && value !== null && !Array.isArray(value);
145
+ }
146
+
147
+ function displayLine(value: unknown): string {
148
+ return typeof value === "string" ? sanitizeTerminalText(value) : "";
149
+ }
150
+
151
+ function documentLines(value: string, width: number, style: Style, prefix = "", prefixStyle = style): string[] {
152
+ const text = sanitizeTerminalDocument(value);
153
+ let contentWidth = 1;
154
+ for (const { segment } of graphemeSegmenter.segment(text)) {
155
+ contentWidth = Math.min(width, Math.max(contentWidth, visibleWidth(segment)));
156
+ }
157
+ // Reduce decoration before it forces a grapheme that fits the viewport into Kit's fallback.
158
+ const visiblePrefix = truncateToWidth(prefix, width - contentWidth, "");
159
+ const prefixWidth = visibleWidth(visiblePrefix);
160
+ return hardWrapTerminalDocument(text, width - prefixWidth).map((line, index) => {
161
+ const decoration = index === 0 ? visiblePrefix : " ".repeat(prefixWidth);
162
+ // Leading marks can change width when they join the decoration's final grapheme.
163
+ const safePrefix = visibleWidth(decoration + line) <= width ? decoration : "";
164
+ return prefixStyle(safePrefix) + style(line);
165
+ });
166
+ }
167
+
168
+ function boundedComponent(render: (width: number) => string[]): Component {
169
+ return {
170
+ render: (width) => (Number.isFinite(width) && width >= 1 ? render(Math.floor(width)) : []),
171
+ // Theme styles are evaluated on every render, so there is no cache to clear.
172
+ invalidate() {},
173
+ };
174
+ }
@@ -26,7 +26,13 @@ export type PlanModeQuestionAnswer = {
26
26
  note?: string;
27
27
  };
28
28
 
29
- type PlanModeQuestionReason = "cancelled" | "ui_unavailable" | "plan_mode_inactive" | "invalid_input";
29
+ type PlanModeQuestionReason =
30
+ | "cancelled"
31
+ | "ui_unavailable"
32
+ | "plan_mode_inactive"
33
+ | "invalid_input"
34
+ | "discussion_requested"
35
+ | "questions_paused";
30
36
 
31
37
  type PlanModeQuestionDetails = {
32
38
  cancelled: boolean;
@@ -146,9 +152,19 @@ export function normalizePlanModeQuestionParams(input: unknown): NormalizePlanMo
146
152
  export async function answerPlanModeQuestions(
147
153
  questions: PlanModeQuestion[],
148
154
  ctx: ExtensionContext,
149
- lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
155
+ lifecycle: {
156
+ isCurrent(): boolean;
157
+ isEnabled(): boolean;
158
+ signal?: AbortSignal;
159
+ discussionRequested?(): boolean;
160
+ },
150
161
  ) {
151
- const answers = await askPlanModeQuestions(questions, ctx, () => lifecycle.isCurrent() && lifecycle.isEnabled());
162
+ const answers = await askPlanModeQuestions(
163
+ questions,
164
+ ctx,
165
+ () => lifecycle.isCurrent() && lifecycle.isEnabled(),
166
+ lifecycle.signal,
167
+ );
152
168
  if (!lifecycle.isCurrent()) {
153
169
  return planModeQuestionCancelled(
154
170
  questions,
@@ -163,6 +179,16 @@ export async function answerPlanModeQuestions(
163
179
  "Plan-mode question cancelled because Plan mode is no longer active.",
164
180
  );
165
181
  }
182
+ if (lifecycle.discussionRequested?.()) {
183
+ return {
184
+ ...planModeQuestionCancelled(
185
+ questions,
186
+ "discussion_requested",
187
+ "The user switched to free discussion without submitting answers. Wait for the user to speak; do not reopen the questionnaire.",
188
+ ),
189
+ terminate: true,
190
+ };
191
+ }
166
192
  if (!answers) {
167
193
  return planModeQuestionCancelled(questions, "cancelled", "User cancelled the Plan-mode question prompt.");
168
194
  }
@@ -173,6 +199,7 @@ export async function askPlanModeQuestions(
173
199
  questions: PlanModeQuestion[],
174
200
  ctx: ExtensionContext,
175
201
  shouldContinue: () => boolean = () => true,
202
+ signal: AbortSignal | undefined = ctx.signal,
176
203
  ): Promise<PlanModeQuestionAnswer[] | undefined> {
177
204
  const { runQuestionnaire, sanitizeTerminalText } = await import("@narumitw/pi-tui-kit");
178
205
  if (!shouldContinue()) return undefined;
@@ -190,7 +217,7 @@ export async function askPlanModeQuestions(
190
217
  questions: runnerQuestions,
191
218
  allowNotes: true,
192
219
  maxTextLength: MAX_PLAN_MODE_RESPONSE_LENGTH,
193
- signal: ctx.signal,
220
+ signal,
194
221
  isCurrent: shouldContinue,
195
222
  });
196
223
  if (!shouldContinue()) return undefined;
package/src/state.ts CHANGED
@@ -4,6 +4,7 @@ import {
4
4
  planFromCompletionDetails,
5
5
  } from "./completion-tool.js";
6
6
  import { type ImplementationModelOverride, isPendingImplementationModelIdentifier } from "./implementation-models.js";
7
+ import type { PlanInteractionMode } from "./interaction-contract.js";
7
8
  import {
8
9
  IMPLEMENTATION_PLAN_RETENTIONS,
9
10
  type ImplementationPlanRetention,
@@ -48,8 +49,18 @@ export interface PlanModeWorkflowToolPolicy {
48
49
  resolved: boolean;
49
50
  }
50
51
 
52
+ export interface PlanInteractionRestoration {
53
+ version: 1;
54
+ mode: PlanInteractionMode;
55
+ boundary: { length: number; hash: string };
56
+ }
57
+
51
58
  export interface PlanModeState {
52
59
  enabled: boolean;
60
+ /** An absent value in an enabled legacy workflow means questions. */
61
+ interactionMode?: PlanInteractionMode;
62
+ /** Historical model-visible anchors survive toggles and exits, not as active interaction state. */
63
+ interactionRestorations?: PlanInteractionRestoration[];
53
64
  latestPlan?: string;
54
65
  latestPlanSource?: PlanCompletionSource;
55
66
  awaitingAction: boolean;
@@ -89,6 +100,12 @@ export function restorePlanModeState(entries: unknown[], stateEntryType: string)
89
100
  if (!isRecord(entry?.data)) return { enabled: false, awaitingAction: false };
90
101
 
91
102
  const enabled = entry.data.enabled === true;
103
+ const interactionMode = entry.data.interactionMode === "discussion" ? "discussion" : "questions";
104
+ const interactionRestorations = Array.isArray(entry.data.interactionRestorations)
105
+ ? entry.data.interactionRestorations
106
+ .map(normalizeInteractionRestoration)
107
+ .filter((value): value is PlanInteractionRestoration => value !== undefined)
108
+ : [];
92
109
  const persistedSource = enabled ? planCompletionSource(entry.data.latestPlanSource) : undefined;
93
110
  const persistedPlan = enabled ? normalizePersistedPlan(entry.data.latestPlan) : undefined;
94
111
  const recoveredPlan = enabled && !persistedPlan ? latestCompletionPlan(branch.slice(stateEntryIndex + 1)) : undefined;
@@ -100,6 +117,8 @@ export function restorePlanModeState(entries: unknown[], stateEntryType: string)
100
117
  : normalizePendingImplementationRuntime(entry.data.pendingImplementationRuntime);
101
118
  return {
102
119
  enabled,
120
+ ...(enabled && entry.data.interactionMode !== undefined ? { interactionMode } : {}),
121
+ ...(interactionRestorations.length ? { interactionRestorations } : {}),
103
122
  latestPlan,
104
123
  latestPlanSource: enabled
105
124
  ? ((persistedPlan ? persistedSource : undefined) ?? (recoveredPlan ? PLAN_MODE_COMPLETE_TOOL_NAME : undefined))
@@ -117,6 +136,27 @@ export function restorePlanModeState(entries: unknown[], stateEntryType: string)
117
136
  };
118
137
  }
119
138
 
139
+ function normalizeInteractionRestoration(value: unknown): PlanInteractionRestoration | undefined {
140
+ if (
141
+ !isRecord(value) ||
142
+ value.version !== 1 ||
143
+ (value.mode !== "questions" && value.mode !== "discussion") ||
144
+ !isRecord(value.boundary)
145
+ )
146
+ return undefined;
147
+ const mode = value.mode;
148
+ const { length, hash } = value.boundary;
149
+ if (
150
+ typeof length !== "number" ||
151
+ !Number.isSafeInteger(length) ||
152
+ length < 0 ||
153
+ typeof hash !== "string" ||
154
+ !/^[a-f0-9]{64}$/u.test(hash)
155
+ )
156
+ return undefined;
157
+ return { version: 1, mode, boundary: { length, hash } };
158
+ }
159
+
120
160
  function normalizeWorkflowToolPolicy(value: unknown): PlanModeWorkflowToolPolicy | undefined {
121
161
  if (value === undefined) return undefined;
122
162
  const denied: PlanModeWorkflowToolPolicy = {