From a80a7c64931850a23178bbec996b8d388b7f66ab Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:04:45 +0000 Subject: [PATCH 01/38] feat(ask): add queued, deferred and expired result contract Types and validation for background, timeoutSeconds and per-question fallback, plus result text that carries the receipt and fallback rules. Nothing is exposed in the registered schema yet. --- pi-ask/src/ask-tool-helpers.ts | 6 +- pi-ask/src/i18n.ts | 44 ++++++++++++++ pi-ask/src/result.ts | 11 ++++ pi-ask/src/state/normalize.ts | 52 ++++++++++++++++- pi-ask/src/state/result.ts | 19 ++++++ pi-ask/src/types.ts | 23 +++++++- pi-ask/tests/contract.test.ts | 103 ++++++++++++++++++++++++++++++++- 7 files changed, 249 insertions(+), 9 deletions(-) diff --git a/pi-ask/src/ask-tool-helpers.ts b/pi-ask/src/ask-tool-helpers.ts index d32364aa..62c9dca2 100644 --- a/pi-ask/src/ask-tool-helpers.ts +++ b/pi-ask/src/ask-tool-helpers.ts @@ -105,11 +105,7 @@ export function renderAskToolResult( } const text = renderResultText(details); return new Text( - details.status === "invalid" || - details.status === "cancelled" || - details.status === "unavailable" - ? theme.fg("warning", text) - : text, + details.status === "submitted" ? text : theme.fg("warning", text), 0, 0 ); diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index e2795a0e..8f230532 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -29,8 +29,23 @@ export interface AskStrings { cancelledSummary: string; /** One-line summary returned to the model when the user submits. */ submittedSummary: string; + /** Receipt returned to the model for a background call. */ + queuedSummary: (requestId: string) => string; + /** Receipt returned to the model when the user chose "answer later". */ + deferredSummary: (requestId: string) => string; + /** Trailer returned to the model after the time limit lapsed. */ + expiredSummary: (fallbackLabels: string[]) => string; + /** Short transcript labels for the non-answer statuses. */ + queuedLabel: string; + deferredLabel: string; + expiredLabel: string; } +const EN_RECEIPT_RULES = + "This is a receipt, not an answer or approval. Continue only with work that does not depend on it; the answer arrives in a later message. Do not ask again."; +const ZH_RECEIPT_RULES = + "这只是回执,不是回答,也不是批准。只继续不依赖该回答的工作;回答会在之后的消息中送达。不要重复提问。"; + const EN_STRINGS: AskStrings = { backTo: (label) => `← Back to ${label}`, done: (count) => `✔ Done (${count} selected)`, @@ -44,6 +59,21 @@ const EN_STRINGS: AskStrings = { recommendedMarker: "(Recommended)", cancelledSummary: "User cancelled the ask flow", submittedSummary: "User submitted the ask flow", + queuedSummary: (requestId) => + `Queued as ${requestId}. ${EN_RECEIPT_RULES}`, + deferredSummary: (requestId) => + `User will answer later (${requestId}). ${EN_RECEIPT_RULES}`, + expiredSummary: (fallbackLabels) => + [ + "No response within the time limit.", + fallbackLabels.length > 0 + ? `Fallback applied for: ${fallbackLabels.join(", ")}.` + : "No fallback was applied.", + "A fallback is your own assumption, not user approval; keep irreversible actions blocked. The user may still correct it.", + ].join(" "), + queuedLabel: "Queued", + deferredLabel: "Answer later", + expiredLabel: "Expired", }; const ZH_STRINGS: AskStrings = { @@ -59,6 +89,20 @@ const ZH_STRINGS: AskStrings = { recommendedMarker: "(推荐)", cancelledSummary: "用户取消了提问流程", submittedSummary: "用户提交了提问流程", + queuedSummary: (requestId) => `已排队,编号 ${requestId}。${ZH_RECEIPT_RULES}`, + deferredSummary: (requestId) => + `用户稍后回答(${requestId})。${ZH_RECEIPT_RULES}`, + expiredSummary: (fallbackLabels) => + [ + "用户未在时限内回应。", + fallbackLabels.length > 0 + ? `已对以下问题应用备选项:${fallbackLabels.join("、")}。` + : "没有应用任何备选项。", + "备选项只是你自己的假设,不是用户批准;不可逆的操作仍须保持阻止。用户之后仍可更正。", + ].join(""), + queuedLabel: "已排队", + deferredLabel: "稍后回答", + expiredLabel: "已超时", }; /** Strings for PI_ASK_LOCALE; any zh* tag picks Simplified Chinese. */ diff --git a/pi-ask/src/result.ts b/pi-ask/src/result.ts index 89e83a0c..d4565a51 100644 --- a/pi-ask/src/result.ts +++ b/pi-ask/src/result.ts @@ -2,6 +2,7 @@ import { CANCELLED_RESULT_TEXT, SUBMITTED_RESULT_TEXT, } from "./constants/text.ts"; +import { askStrings } from "./i18n.ts"; import { formatResultLines } from "./result-format.ts"; import type { AskResult } from "./types.ts"; @@ -16,6 +17,16 @@ export function renderResultText(result: AskResult): string { return "Needs user input"; } + if (result.status === "queued") { + return askStrings().queuedLabel; + } + if (result.status === "deferred") { + return askStrings().deferredLabel; + } + const lines = formatResultLines(result, { mode: "render" }); + if (result.status === "expired") { + return [askStrings().expiredLabel, ...lines].join("\n"); + } return lines.join("\n") || SUBMITTED_RESULT_TEXT; } diff --git a/pi-ask/src/state/normalize.ts b/pi-ask/src/state/normalize.ts index ee320c26..223c68e7 100644 --- a/pi-ask/src/state/normalize.ts +++ b/pi-ask/src/state/normalize.ts @@ -26,10 +26,18 @@ export function collectValidationIssues( ): AskValidationIssue[] { const collector = createIssueCollector(); validateQuestions(params.questions, collector); + validateCallOptions(params, collector); return collector.issues; } -const QUESTION_SHAPE_KEYS = ["id", "label", "prompt", "type", "options"]; +const QUESTION_SHAPE_KEYS = [ + "id", + "label", + "prompt", + "type", + "options", + "fallback", +]; export function prepareAskParams(input: unknown): unknown { if (!isRecord(input)) { @@ -119,12 +127,14 @@ function normalizeQuestion( index: number ): AskQuestion { const type = normalizeQuestionType(question.type); + const fallback = normalizeFallback(question.fallback); return { id: question.id.trim(), label: question.label?.trim() || `Q${index + 1}`, prompt: question.prompt.trim(), type, options: type === "text" ? [] : (question.options ?? []).map(normalizeOption), + ...(fallback === undefined ? {} : { fallback }), }; } @@ -139,6 +149,30 @@ function normalizeOption(option: AskOption): AskOption { }; } +function normalizeFallback(value: unknown): string | undefined { + return typeof value === "string" ? value.trim() : undefined; +} + +function validateCallOptions(params: AskParams, collector: IssueCollector) { + const { background, timeoutSeconds } = params; + if (background !== undefined && typeof background !== "boolean") { + collector.add("background", "background must be true or false"); + } + if ( + timeoutSeconds !== undefined && + !( + typeof timeoutSeconds === "number" && + Number.isFinite(timeoutSeconds) && + timeoutSeconds > 0 + ) + ) { + collector.add( + "timeoutSeconds", + "timeoutSeconds must be a positive number of seconds" + ); + } +} + function validateQuestions( questions: AskParams["questions"], collector: IssueCollector @@ -199,6 +233,12 @@ function validateQuestion( `Question ${questionNumber}: text questions have no options` ); } + if (question.fallback !== undefined) { + collector.add( + `${questionPath}.fallback`, + `Question ${questionNumber}: text questions cannot have a fallback` + ); + } return; } @@ -221,6 +261,16 @@ function validateQuestion( `${questionPath}.options[${optionIndex}]` ); } + + if ( + question.fallback !== undefined && + !optionValues.has(normalizeFallback(question.fallback) ?? "") + ) { + collector.add( + `${questionPath}.fallback`, + `Question ${questionNumber}: fallback ${JSON.stringify(question.fallback)} must match an option value` + ); + } } function validateOption( diff --git a/pi-ask/src/state/result.ts b/pi-ask/src/state/result.ts index a76b3c21..3d126ff0 100644 --- a/pi-ask/src/state/result.ts +++ b/pi-ask/src/state/result.ts @@ -65,11 +65,30 @@ export function summarizeResult(result: AskResult): string { if (result.status === "invalid") { return "Invalid tool payload"; } + // Receipts carry their own rules so the guidance costs tokens only when + // it applies, instead of living in the recurring prompt guidelines. + if (result.status === "queued") { + return askStrings().queuedSummary(result.requestId ?? ""); + } + if (result.status === "deferred") { + return askStrings().deferredSummary(result.requestId ?? ""); + } const lines = formatResultLines(result, { mode: "summary" }); + if (result.status === "expired") { + lines.push(askStrings().expiredSummary(expiredLabels(result))); + return lines.join("\n"); + } return lines.join("\n") || askStrings().submittedSummary; } +function expiredLabels(result: AskResult): string[] { + const expired = new Set(result.expired ?? []); + return result.questions + .filter((question) => expired.has(question.id)) + .map((question) => question.label); +} + export function hasAnswerContent(state: AskState, questionId: string): boolean { const answer = state.answers[questionId]; return !!answer && !isAnswerEmpty(answer); diff --git a/pi-ask/src/types.ts b/pi-ask/src/types.ts index 0acd9fb3..8d5e97c2 100644 --- a/pi-ask/src/types.ts +++ b/pi-ask/src/types.ts @@ -8,6 +8,8 @@ export interface AskOption { } export interface AskQuestionInput { + /** Option `value` applied if the call's time limit lapses. Never on `text`. */ + fallback?: string; id: string; label?: string; options?: AskOption[]; @@ -16,7 +18,11 @@ export interface AskQuestionInput { } export interface AskParams { + /** Queue the form and return a `queued` receipt at once. */ + background?: boolean; questions: AskQuestionInput[]; + /** Time limit in seconds, counted from when the form is on screen. */ + timeoutSeconds?: number; title?: string; } @@ -69,16 +75,31 @@ export interface AskQuestionSummary { type: AskQuestionType; } +/** + * `queued` and `deferred` are receipts, not answers: the form is still open + * and its answer arrives later. `expired` carries declared fallbacks only. + */ export type AskResultStatus = | "submitted" | "cancelled" | "unavailable" - | "invalid"; + | "invalid" + | "queued" + | "deferred" + | "expired"; export interface AskResult { answers: Record; + /** Why the user cancelled, when they said. */ + comment?: string; error?: AskValidationError; + /** Question ids whose answer is an auto-applied fallback (`expired` only). */ + expired?: string[]; questions: AskQuestionSummary[]; + /** Journal id of the form; ties receipts to the answer delivered later. */ + requestId?: string; + /** Question ids the user explicitly declined. Skipped is not approval. */ + skipped?: string[]; status: AskResultStatus; title?: string; unanswered: string[]; diff --git a/pi-ask/tests/contract.test.ts b/pi-ask/tests/contract.test.ts index c56d5f25..746f58b9 100644 --- a/pi-ask/tests/contract.test.ts +++ b/pi-ask/tests/contract.test.ts @@ -12,12 +12,12 @@ import { serializeAnswer } from "../src/state/answers.ts"; import { createInitialState } from "../src/state/create.ts"; import { collectValidationIssues } from "../src/state/normalize.ts"; import { cycleCurrentQuestionType } from "../src/state/question-type.ts"; -import { toAskResult } from "../src/state/result.ts"; +import { summarizeResult, toAskResult } from "../src/state/result.ts"; import { confirmCurrentSelection, toggleCurrentMultiOption, } from "../src/state/transitions.ts"; -import type { AskParams } from "../src/types.ts"; +import type { AskParams, AskResult } from "../src/types.ts"; function registerMockTool() { const tools: Record[] = []; @@ -225,3 +225,102 @@ test("commands and config path are first-party", () => { assert.equal(DEFAULT_ASK_CONFIG.behaviour.doublePressReviewShortcuts, true); assert.deepEqual(DEFAULT_ASK_CONFIG.keymaps.main.changeQuestionType, ["t"]); }); + +const CHOICE = { + id: "db", + label: "DB", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "sqlite", label: "SQLite" }, + ], +}; + +test("fallback must name an option value and is refused on text questions", () => { + assert.deepEqual( + collectValidationIssues({ questions: [{ ...CHOICE, fallback: "sqlite" }] }), + [] + ); + assert.deepEqual( + collectValidationIssues({ + questions: [{ ...CHOICE, fallback: "mysql" }], + }).map((issue) => issue.path), + ["questions[0].fallback"] + ); + assert.deepEqual( + collectValidationIssues({ + questions: [ + { id: "why", prompt: "Why?", type: "text", fallback: "because" }, + ], + }).map((issue) => issue.path), + ["questions[0].fallback"] + ); + assert.equal( + createInitialState({ questions: [{ ...CHOICE, fallback: " sqlite " }] }) + .questions[0]?.fallback, + "sqlite" + ); +}); + +test("timeoutSeconds must be positive and finite; background must be boolean", () => { + for (const timeoutSeconds of [0, -5, Number.NaN, Number.POSITIVE_INFINITY]) { + assert.deepEqual( + collectValidationIssues({ questions: [CHOICE], timeoutSeconds }).map( + (issue) => issue.path + ), + ["timeoutSeconds"] + ); + } + assert.deepEqual( + collectValidationIssues({ + questions: [CHOICE], + timeoutSeconds: 45, + background: true, + }), + [] + ); + assert.deepEqual( + collectValidationIssues({ + questions: [CHOICE], + background: "yes", + } as unknown as AskParams).map((issue) => issue.path), + ["background"] + ); +}); + +function receipt(overrides: Partial): AskResult { + return { + ...toAskResult(createInitialState({ questions: [CHOICE] })), + requestId: "ask-1", + ...overrides, + }; +} + +test("queued and deferred results are receipts that carry their own rules", () => { + for (const status of ["queued", "deferred"] as const) { + const text = summarizeResult(receipt({ status })); + assert.ok(text.includes("ask-1")); + assert.ok(text.includes("not an answer or approval")); + assert.ok(text.includes("Do not ask again")); + assert.ok(!text.includes("(no answer)")); + } +}); + +test("expired results name applied fallbacks and deny approval", () => { + const text = summarizeResult( + receipt({ + status: "expired", + answers: { db: { values: ["sqlite"], labels: ["SQLite"] } }, + unanswered: [], + expired: ["db"], + }) + ); + assert.ok(text.includes("DB: SQLite")); + assert.ok(text.includes("Fallback applied for: DB.")); + assert.ok(text.includes("not user approval")); + assert.ok(text.includes("keep irreversible actions blocked")); + + const none = summarizeResult(receipt({ status: "expired", expired: [] })); + assert.ok(none.includes("DB: (no answer)")); + assert.ok(none.includes("No fallback was applied.")); +}); From c1216c8effcfce1e9252633bdd9cf9e9c8851fdd Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:06:04 +0000 Subject: [PATCH 02/38] feat(ask): add expiry and background config keys expiry.enabled, expiry.minSeconds (30s floor) and behaviour.background default on. Older configs keep loading; peek() reads config for registration without creating the file. --- pi-ask/src/config/defaults.ts | 21 +++++++++++ pi-ask/src/config/schema.ts | 15 ++++++++ pi-ask/src/config/store.ts | 21 +++++++++++ pi-ask/tests/config-store.test.ts | 58 ++++++++++++++++++++++++++++++ pi-ask/tests/settings-list.test.ts | 2 ++ 5 files changed, 117 insertions(+) diff --git a/pi-ask/src/config/defaults.ts b/pi-ask/src/config/defaults.ts index ff099095..934b5c9f 100644 --- a/pi-ask/src/config/defaults.ts +++ b/pi-ask/src/config/defaults.ts @@ -12,6 +12,7 @@ import type { const DEFAULT_EXTRACTION_RETRIES = 1; const MAX_EXTRACTION_RETRIES = 3; const DEFAULT_EXTRACTION_TIMEOUT_MS = 30_000; +const DEFAULT_EXPIRY_MIN_SECONDS = 30; export const DEFAULT_ASK_CONFIG: AskConfig = { answer: { @@ -21,10 +22,15 @@ export const DEFAULT_ASK_CONFIG: AskConfig = { }, behaviour: { autoSubmitWhenAnsweredWithoutNotes: false, + background: true, confirmDismissWhenDirty: true, doublePressReviewShortcuts: true, showFooterHints: true, }, + expiry: { + enabled: true, + minSeconds: DEFAULT_EXPIRY_MIN_SECONDS, + }, keymaps: structuredClone(DEFAULT_ASK_KEYMAPS), notifications: { channels: ["bell"], @@ -55,6 +61,9 @@ export function normalizeAskConfig( autoSubmitWhenAnsweredWithoutNotes: config?.behaviour?.autoSubmitWhenAnsweredWithoutNotes ?? DEFAULT_ASK_CONFIG.behaviour.autoSubmitWhenAnsweredWithoutNotes, + background: + config?.behaviour?.background ?? + DEFAULT_ASK_CONFIG.behaviour.background, confirmDismissWhenDirty: config?.behaviour?.confirmDismissWhenDirty ?? DEFAULT_ASK_CONFIG.behaviour.confirmDismissWhenDirty, @@ -65,6 +74,13 @@ export function normalizeAskConfig( config?.behaviour?.showFooterHints ?? DEFAULT_ASK_CONFIG.behaviour.showFooterHints, }, + expiry: { + enabled: config?.expiry?.enabled ?? DEFAULT_ASK_CONFIG.expiry.enabled, + minSeconds: positiveNumberOrDefault( + config?.expiry?.minSeconds, + DEFAULT_EXPIRY_MIN_SECONDS + ), + }, keymaps: mergeKeymaps(config?.keymaps), notifications: { channels: normalizeNotificationChannels(config?.notifications?.channels), @@ -87,11 +103,16 @@ export function toAskConfigFile(config: AskConfig): AskConfigFile { behaviour: { autoSubmitWhenAnsweredWithoutNotes: normalized.behaviour.autoSubmitWhenAnsweredWithoutNotes, + background: normalized.behaviour.background, confirmDismissWhenDirty: normalized.behaviour.confirmDismissWhenDirty, doublePressReviewShortcuts: normalized.behaviour.doublePressReviewShortcuts, showFooterHints: normalized.behaviour.showFooterHints, }, + expiry: { + enabled: normalized.expiry.enabled, + minSeconds: normalized.expiry.minSeconds, + }, keymaps: structuredClone(normalized.keymaps), notifications: { channels: normalized.notifications.channels, diff --git a/pi-ask/src/config/schema.ts b/pi-ask/src/config/schema.ts index a8eb34b7..774897fb 100644 --- a/pi-ask/src/config/schema.ts +++ b/pi-ask/src/config/schema.ts @@ -76,11 +76,18 @@ export const AskConfigFileSchema = Type.Object({ behaviour: Type.Optional( Type.Object({ autoSubmitWhenAnsweredWithoutNotes: Type.Optional(Type.Boolean()), + background: Type.Optional(Type.Boolean()), confirmDismissWhenDirty: Type.Optional(Type.Boolean()), doublePressReviewShortcuts: Type.Optional(Type.Boolean()), showFooterHints: Type.Optional(Type.Boolean()), }) ), + expiry: Type.Optional( + Type.Object({ + enabled: Type.Optional(Type.Boolean()), + minSeconds: Type.Optional(Type.Number()), + }) + ), keymaps: Type.Optional(AskConfigKeymapsSchema), notifications: Type.Optional( Type.Object({ @@ -145,10 +152,18 @@ export interface AskConfig { }; behaviour: { autoSubmitWhenAnsweredWithoutNotes: boolean; + /** `false` removes `background` from the schema; every call blocks. */ + background: boolean; confirmDismissWhenDirty: boolean; doublePressReviewShortcuts: boolean; showFooterHints: boolean; }; + expiry: { + /** `false` removes `timeoutSeconds` and `fallback` from the schema. */ + enabled: boolean; + /** Shorter requested limits are raised to this floor. */ + minSeconds: number; + }; keymaps: AskConfigKeymaps; notifications: { channels: AskNotificationChannel[]; diff --git a/pi-ask/src/config/store.ts b/pi-ask/src/config/store.ts index 45dd1e3a..858f37f6 100644 --- a/pi-ask/src/config/store.ts +++ b/pi-ask/src/config/store.ts @@ -58,6 +58,27 @@ export class AskConfigStore { return (await this.ensureLoaded()).config; } + /** + * Read-only load for extension registration: never creates or rewrites the + * file, and falls back to defaults on any problem. Schema-shaping settings + * are read once here so they change on reload, not mid-session. + */ + async peek(): Promise { + if (this.config) { + return this.config; + } + try { + const content = await readConfigFileIfPresent(this.configPath); + const parsed = content === undefined ? undefined : parseJson(content); + if (parsed?.ok && validateAskConfigFile.Check(parsed.value)) { + return normalizeAskConfig(parsed.value); + } + } catch { + // Unreadable config: registration proceeds on defaults. + } + return normalizeAskConfig(DEFAULT_ASK_CONFIG); + } + async save(config: AskConfig | Partial): Promise { const normalized = normalizeAskConfig(config); const content = JSON.stringify(toAskConfigFile(normalized), null, 2).concat( diff --git a/pi-ask/tests/config-store.test.ts b/pi-ask/tests/config-store.test.ts index 8e6719ee..3d35d333 100644 --- a/pi-ask/tests/config-store.test.ts +++ b/pi-ask/tests/config-store.test.ts @@ -16,6 +16,7 @@ function expectedConfigFile() { schemaVersion: 1, answer: DEFAULT_ASK_CONFIG.answer, behaviour: DEFAULT_ASK_CONFIG.behaviour, + expiry: DEFAULT_ASK_CONFIG.expiry, keymaps: DEFAULT_ASK_CONFIG.keymaps, notifications: DEFAULT_ASK_CONFIG.notifications, }; @@ -102,3 +103,60 @@ test("config store leaves invalid files unchanged", async () => { assert.equal(result.notice?.kind, "error"); assert.equal(await readFile(path, "utf-8"), "{not json"); }); + +test("expiry and background default on with a 30 second floor", () => { + assert.deepEqual(DEFAULT_ASK_CONFIG.expiry, { enabled: true, minSeconds: 30 }); + assert.equal(DEFAULT_ASK_CONFIG.behaviour.background, true); +}); + +test("configs written before expiry existed keep loading with defaults", async () => { + const path = await makeTempPath("pi-ask-config-legacy-"); + const { expiry: _expiry, behaviour, ...legacy } = expectedConfigFile(); + const { background: _background, ...legacyBehaviour } = behaviour; + await writeFile( + path, + JSON.stringify({ + ...legacy, + behaviour: { ...legacyBehaviour, showFooterHints: false }, + futureKey: { anything: true }, + }) + ); + const result = await new AskConfigStore(path).ensureLoaded(); + assert.equal(result.notice, undefined); + assert.equal(result.config.behaviour.showFooterHints, false); + assert.equal(result.config.behaviour.background, true); + assert.deepEqual(result.config.expiry, DEFAULT_ASK_CONFIG.expiry); +}); + +test("expiry and background settings are normalised", async () => { + const path = await makeTempPath("pi-ask-config-expiry-"); + await writeFile( + path, + JSON.stringify({ + behaviour: { background: false }, + expiry: { enabled: false, minSeconds: 90 }, + }) + ); + const loaded = (await new AskConfigStore(path).ensureLoaded()).config; + assert.equal(loaded.behaviour.background, false); + assert.deepEqual(loaded.expiry, { enabled: false, minSeconds: 90 }); + + for (const minSeconds of [0, -1]) { + await writeFile(path, JSON.stringify({ expiry: { minSeconds } })); + const config = (await new AskConfigStore(path).ensureLoaded()).config; + assert.deepEqual(config.expiry, { enabled: true, minSeconds: 30 }); + } +}); + +test("peek reads config without creating the file", async () => { + const path = await makeTempPath("pi-ask-config-peek-"); + const store = new AskConfigStore(path); + assert.deepEqual(await store.peek(), DEFAULT_ASK_CONFIG); + await assert.rejects(readFile(path, "utf-8"), { code: "ENOENT" }); + + await writeFile(path, JSON.stringify({ expiry: { enabled: false } })); + assert.equal((await store.peek()).expiry.enabled, false); + await writeFile(path, "{not json"); + assert.deepEqual(await store.peek(), DEFAULT_ASK_CONFIG); + assert.equal(await readFile(path, "utf-8"), "{not json"); +}); diff --git a/pi-ask/tests/settings-list.test.ts b/pi-ask/tests/settings-list.test.ts index 9136c1a1..3af3c05d 100644 --- a/pi-ask/tests/settings-list.test.ts +++ b/pi-ask/tests/settings-list.test.ts @@ -12,10 +12,12 @@ const savedConfig: AskConfig = { }, behaviour: { autoSubmitWhenAnsweredWithoutNotes: false, + background: true, confirmDismissWhenDirty: true, doublePressReviewShortcuts: true, showFooterHints: true, }, + expiry: { ...DEFAULT_ASK_CONFIG.expiry }, keymaps: DEFAULT_ASK_CONFIG.keymaps, notifications: { channels: ["bell"], From f7f98600d5dd28d7a09394a0acad349b3b94af11 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:07:23 +0000 Subject: [PATCH 03/38] feat(ask): gate async schema fields and enforce token ceilings buildAskParamsSchema registers background, timeoutSeconds and fallback only for features that have shipped and that config leaves enabled. The footprint measure is shared by npm run tokens and a ceiling test (450 all enabled, 420 with expiry disabled). --- pi-ask/scripts/footprint.ts | 61 +++++++++++++++++++ pi-ask/scripts/token-report.mjs | 47 ++++++--------- pi-ask/src/ask-tool.ts | 13 +++- pi-ask/src/features.ts | 39 ++++++++++++ pi-ask/src/index.ts | 10 +++- pi-ask/src/schema.ts | 62 ++++++++++++++++++- pi-ask/tests/token-ceiling.test.ts | 96 ++++++++++++++++++++++++++++++ scripts/packages.mjs | 2 +- 8 files changed, 294 insertions(+), 36 deletions(-) create mode 100644 pi-ask/scripts/footprint.ts create mode 100644 pi-ask/src/features.ts create mode 100644 pi-ask/tests/token-ceiling.test.ts diff --git a/pi-ask/scripts/footprint.ts b/pi-ask/scripts/footprint.ts new file mode 100644 index 00000000..9da7e836 --- /dev/null +++ b/pi-ask/scripts/footprint.ts @@ -0,0 +1,61 @@ +/** + * Recurring model-facing context footprint of a registered tool: description, + * prompt snippet/guidelines, and the JSON parameter schema. Tokens are a fixed + * character-proxy estimate (ceil(chars / 4)), not provider tokenizer billing. + * Shared by `npm run tokens` and the token-ceiling test. + */ +import { type AskToolOptions, registerAskTool } from "../src/ask-tool.ts"; + +export interface FootprintPart { + chars: number; + name: string; + tokens: number; +} + +export interface Footprint { + parts: FootprintPart[]; + totalChars: number; + totalTokens: number; +} + +interface RegisteredTool { + description: string; + parameters: unknown; + promptGuidelines?: string[]; + promptSnippet?: string; +} + +export function measureAskToolFootprint(options?: AskToolOptions): Footprint { + let tool: RegisteredTool | undefined; + registerAskTool( + { + registerTool(registered: RegisteredTool) { + tool = registered; + }, + } as never, + options + ); + if (!tool) { + throw new Error("ask_user was not registered"); + } + return measureToolFootprint(tool); +} + +export function measureToolFootprint(tool: RegisteredTool): Footprint { + const texts = { + description: tool.description, + promptSnippet: tool.promptSnippet ?? "", + promptGuidelines: (tool.promptGuidelines ?? []).join("\n"), + parameters: JSON.stringify(tool.parameters), + }; + const parts = Object.entries(texts).map(([name, text]) => ({ + name, + chars: text.length, + tokens: Math.ceil(text.length / 4), + })); + return { + parts, + totalChars: parts.reduce((sum, part) => sum + part.chars, 0), + totalTokens: parts.reduce((sum, part) => sum + part.tokens, 0), + }; +} diff --git a/pi-ask/scripts/token-report.mjs b/pi-ask/scripts/token-report.mjs index 3818be61..94941ae5 100644 --- a/pi-ask/scripts/token-report.mjs +++ b/pi-ask/scripts/token-report.mjs @@ -1,34 +1,25 @@ /** - * Reports the recurring model-facing context footprint of the ask_user tool: - * description, prompt snippet/guidelines, and the JSON parameter schema. - * Tokens are a fixed character-proxy estimate (ceil(chars / 4)), not provider - * tokenizer billing. Run with `npm run tokens`. + * Reports the recurring model-facing context footprint of the ask_user tool. + * Measuring lives in ./footprint.ts, shared with the token-ceiling test. + * Run with `npm run tokens`. */ -import { registerAskTool } from "../src/ask-tool.ts"; +import { ALL_ASK_FEATURES, SHIPPED_ASK_FEATURES } from "../src/features.ts"; +import { measureAskToolFootprint } from "./footprint.ts"; -let tool; -registerAskTool({ - registerTool(registered) { - tool = registered; - }, -}); - -const parts = { - description: tool.description, - promptSnippet: tool.promptSnippet, - promptGuidelines: tool.promptGuidelines.join("\n"), - parameters: JSON.stringify(tool.parameters), -}; - -const estimate = (text) => Math.ceil(text.length / 4); -let totalChars = 0; -let totalTokens = 0; +const row = (name, chars, tokens) => + console.log(` ${name.padEnd(16)} ${String(chars).padStart(5)} / ${tokens}`); +const shipped = measureAskToolFootprint({ features: SHIPPED_ASK_FEATURES }); console.log("ask_user context footprint (chars / est. tokens)"); -for (const [name, text] of Object.entries(parts)) { - const tokens = estimate(text); - totalChars += text.length; - totalTokens += tokens; - console.log(` ${name.padEnd(16)} ${String(text.length).padStart(5)} / ${tokens}`); +for (const part of shipped.parts) { + row(part.name, part.chars, part.tokens); } -console.log(` ${"total".padEnd(16)} ${String(totalChars).padStart(5)} / ${totalTokens}`); +row("total", shipped.totalChars, shipped.totalTokens); + +const all = measureAskToolFootprint({ features: ALL_ASK_FEATURES }); +const noExpiry = measureAskToolFootprint({ + features: { ...ALL_ASK_FEATURES, expiry: false }, +}); +console.log("with optional fields (ceilings 450 / 420)"); +row("all enabled", all.totalChars, all.totalTokens); +row("expiry disabled", noExpiry.totalChars, noExpiry.totalTokens); diff --git a/pi-ask/src/ask-tool.ts b/pi-ask/src/ask-tool.ts index 445a921a..8050731d 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -12,13 +12,20 @@ import { successfulResponse, validateParams, } from "./ask-tool-helpers.ts"; -import { AskParamsSchema, stripSchemaDescriptions } from "./schema.ts"; +import { type AskFeatures, NO_ASK_FEATURES } from "./features.ts"; +import { buildAskParamsSchema, stripSchemaDescriptions } from "./schema.ts"; import { prepareAskParams } from "./state/normalize.ts"; import type { AskParams } from "./types.ts"; import { runAskFlow } from "./ui/controller.ts"; import { runRpcAskFlow } from "./ui/rpc-flow.ts"; -export function registerAskTool(pi: ExtensionAPI) { +export interface AskToolOptions { + /** Optional schema fields to register; see `resolveAskFeatures`. */ + features?: AskFeatures; +} + +export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) { + const features = options.features ?? NO_ASK_FEATURES; pi.registerTool({ name: "ask_user", label: "Ask User", @@ -27,7 +34,7 @@ export function registerAskTool(pi: ExtensionAPI) { "Interview the user to clarify gaps in context or requirements, get missing authorization, or brainstorm", promptGuidelines: [...ASK_TOOL_PROMPT_GUIDELINES], // Field prose lives in the guidelines; the registered schema stays lean. - parameters: stripSchemaDescriptions(AskParamsSchema), + parameters: stripSchemaDescriptions(buildAskParamsSchema(features)), prepareArguments: (args) => prepareAskParams(args) as AskParams, execute: (_toolCallId, params, signal, _onUpdate, ctx) => executeAskTool(params as AskParams, ctx, signal), diff --git a/pi-ask/src/features.ts b/pi-ask/src/features.ts new file mode 100644 index 00000000..0a262e2b --- /dev/null +++ b/pi-ask/src/features.ts @@ -0,0 +1,39 @@ +import type { AskConfig } from "./config/schema.ts"; +import type { AskSchemaFeatures } from "./schema.ts"; + +/** + * Optional model-facing surface of `ask_user`. A feature is registered only + * when its behaviour has shipped AND the user's config leaves it enabled; + * otherwise its fields are absent from the schema and cost nothing. + */ +export type AskFeatures = AskSchemaFeatures; + +export const NO_ASK_FEATURES: AskFeatures = { + background: false, + expiry: false, +}; + +export const ALL_ASK_FEATURES: AskFeatures = { + background: true, + expiry: true, +}; + +/** + * Features whose behaviour is implemented. Flip a flag to `true` in the same + * change that makes the tool honour the field; config can only narrow this. + */ +export const SHIPPED_ASK_FEATURES: AskFeatures = { + background: false, + expiry: false, +}; + +/** Read once at registration, so a config change applies on reload only. */ +export function resolveAskFeatures( + config: Pick, + shipped: AskFeatures = SHIPPED_ASK_FEATURES +): AskFeatures { + return { + background: shipped.background && config.behaviour.background, + expiry: shipped.expiry && config.expiry.enabled, + }; +} diff --git a/pi-ask/src/index.ts b/pi-ask/src/index.ts index f295fd5c..e8a661a4 100644 --- a/pi-ask/src/index.ts +++ b/pi-ask/src/index.ts @@ -2,11 +2,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { registerAnswerCommands } from "./answer-commands.ts"; import { registerAskSettingsCommand } from "./ask-settings-command.ts"; import { registerAskTool } from "./ask-tool.ts"; -import { resetAskConfigStore } from "./config/store.ts"; +import { getAskConfigStore, resetAskConfigStore } from "./config/store.ts"; +import { resolveAskFeatures } from "./features.ts"; -export default function askExtension(pi: ExtensionAPI) { +export default async function askExtension(pi: ExtensionAPI) { resetAskConfigStore(); - registerAskTool(pi); + // Schema-shaping settings are fixed here, so toggling them takes a reload + // and never invalidates the prompt cache mid-session. + const features = resolveAskFeatures(await getAskConfigStore().peek()); + registerAskTool(pi, { features }); registerAskSettingsCommand(pi); registerAnswerCommands(pi); } diff --git a/pi-ask/src/schema.ts b/pi-ask/src/schema.ts index f954e04d..9d39b2fa 100644 --- a/pi-ask/src/schema.ts +++ b/pi-ask/src/schema.ts @@ -1,6 +1,9 @@ import { StringEnum } from "@earendil-works/pi-ai"; import { Type } from "typebox"; +const QUESTIONS_DESCRIPTION = + "Questions to ask in the interactive clarification flow"; + export const AskOptionSchema = Type.Object({ value: Type.String({ description: @@ -58,10 +61,67 @@ export const AskParamsSchema = Type.Object({ }) ), questions: Type.Array(AskQuestionSchema, { - description: "Questions to ask in the interactive clarification flow", + description: QUESTIONS_DESCRIPTION, }), }); +/** Which optional model-facing fields the registered schema carries. */ +export interface AskSchemaFeatures { + /** `background` on the call. */ + background: boolean; + /** `timeoutSeconds` on the call and `fallback` on each question. */ + expiry: boolean; +} + +const AskQuestionWithFallbackSchema = Type.Object({ + ...AskQuestionSchema.properties, + fallback: Type.Optional( + Type.String({ + description: + "Option value applied if timeoutSeconds lapses; omit to leave the question unanswered", + }) + ), +}); + +/** Every optional field present; `buildAskParamsSchema` narrows it. */ +export const AskParamsFullSchema = Type.Object({ + title: AskParamsSchema.properties.title, + questions: Type.Array(AskQuestionWithFallbackSchema, { + description: QUESTIONS_DESCRIPTION, + }), + background: Type.Optional( + Type.Boolean({ + description: + "Queue the form and return a receipt at once; the answer arrives later", + }) + ), + timeoutSeconds: Type.Optional( + Type.Number({ + description: + "Time limit in seconds, counted from when the form is on screen", + }) + ), +}); + +/** + * Parameter schema for the given features. A disabled feature's fields are + * absent, not merely ignored, so they cost no recurring context. Statically + * it is the full shape, since every gated field is optional. + */ +export function buildAskParamsSchema( + features: AskSchemaFeatures +): typeof AskParamsFullSchema { + const { title, questions, background, timeoutSeconds } = + AskParamsFullSchema.properties; + const properties = { + title, + questions: features.expiry ? questions : AskParamsSchema.properties.questions, + ...(features.background ? { background } : {}), + ...(features.expiry ? { timeoutSeconds } : {}), + }; + return Type.Object(properties) as unknown as typeof AskParamsFullSchema; +} + const AnswerExtractionQuestionSchema = Type.Object({ id: Type.String({ description: "Stable snake_case question identifier" }), label: AskQuestionSchema.properties.label, diff --git a/pi-ask/tests/token-ceiling.test.ts b/pi-ask/tests/token-ceiling.test.ts new file mode 100644 index 00000000..00c09b54 --- /dev/null +++ b/pi-ask/tests/token-ceiling.test.ts @@ -0,0 +1,96 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { measureAskToolFootprint } from "../scripts/footprint.ts"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; +import { + ALL_ASK_FEATURES, + type AskFeatures, + NO_ASK_FEATURES, + resolveAskFeatures, + SHIPPED_ASK_FEATURES, +} from "../src/features.ts"; + +/** Est. tokens, measured exactly as `npm run tokens` does. */ +const CEILING_ALL_ENABLED = 450; +const CEILING_EXPIRY_DISABLED = 420; + +function schemaKeys(features: AskFeatures) { + let parameters: any; + registerAskTool( + { + registerTool(tool: { parameters: unknown }) { + parameters = tool.parameters; + }, + } as never, + { features } + ); + return { + call: Object.keys(parameters.properties), + question: Object.keys(parameters.properties.questions.items.properties), + }; +} + +test("ask_user footprint stays under the ceiling with everything enabled", () => { + const { totalTokens } = measureAskToolFootprint({ + features: ALL_ASK_FEATURES, + }); + assert.ok( + totalTokens <= CEILING_ALL_ENABLED, + `${totalTokens} est. tokens exceeds the ${CEILING_ALL_ENABLED} ceiling` + ); +}); + +test("ask_user footprint stays under the lower ceiling with expiry disabled", () => { + for (const features of [ + { ...ALL_ASK_FEATURES, expiry: false }, + NO_ASK_FEATURES, + SHIPPED_ASK_FEATURES, + ]) { + const { totalTokens } = measureAskToolFootprint({ features }); + assert.ok( + totalTokens <= CEILING_EXPIRY_DISABLED, + `${totalTokens} est. tokens exceeds the ${CEILING_EXPIRY_DISABLED} ceiling` + ); + } +}); + +test("a disabled feature is absent from the registered schema", () => { + assert.deepEqual(schemaKeys(NO_ASK_FEATURES), { + call: ["title", "questions"], + question: ["id", "label", "prompt", "type", "options"], + }); + const all = schemaKeys(ALL_ASK_FEATURES); + assert.deepEqual(all.call, [ + "title", + "questions", + "background", + "timeoutSeconds", + ]); + assert.ok(all.question.includes("fallback")); + + const noExpiry = schemaKeys({ ...ALL_ASK_FEATURES, expiry: false }); + assert.deepEqual(noExpiry.call, ["title", "questions", "background"]); + assert.ok(!noExpiry.question.includes("fallback")); +}); + +test("config can only narrow the shipped features", () => { + assert.deepEqual( + resolveAskFeatures(DEFAULT_ASK_CONFIG, ALL_ASK_FEATURES), + ALL_ASK_FEATURES + ); + assert.deepEqual( + resolveAskFeatures( + { + behaviour: { ...DEFAULT_ASK_CONFIG.behaviour, background: false }, + expiry: { ...DEFAULT_ASK_CONFIG.expiry, enabled: false }, + }, + ALL_ASK_FEATURES + ), + NO_ASK_FEATURES + ); + assert.deepEqual( + resolveAskFeatures(DEFAULT_ASK_CONFIG, NO_ASK_FEATURES), + NO_ASK_FEATURES + ); +}); diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 91eb7a2f..25b8a74a 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,7 +2,7 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts"], commands: ["answer", "ask-settings"], tools: ["ask_user"], }, "pi-automode": { From 8b0333b91d7c9ff15ba5c847393a09525bfa3f23 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:14:51 +0000 Subject: [PATCH 04/38] feat(ask): add session journal entries and branch replay Journal entry types for forms, drafts, defers, outcomes and delivery markers, a writer, and a pure reducer that rebuilds form records from the active branch: interrupted forms, the FIFO queue, reopenable expired forms and undelivered outcomes. --- pi-ask/src/journal/entries.ts | 148 +++++++++++++++++ pi-ask/src/journal/journal.ts | 157 ++++++++++++++++++ pi-ask/src/journal/replay.ts | 200 ++++++++++++++++++++++ pi-ask/src/state/draft.ts | 57 +++++++ pi-ask/tests/draft.test.ts | 85 ++++++++++ pi-ask/tests/journal-replay.test.ts | 247 ++++++++++++++++++++++++++++ 6 files changed, 894 insertions(+) create mode 100644 pi-ask/src/journal/entries.ts create mode 100644 pi-ask/src/journal/journal.ts create mode 100644 pi-ask/src/journal/replay.ts create mode 100644 pi-ask/src/state/draft.ts create mode 100644 pi-ask/tests/draft.test.ts create mode 100644 pi-ask/tests/journal-replay.test.ts diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts new file mode 100644 index 00000000..54dea935 --- /dev/null +++ b/pi-ask/src/journal/entries.ts @@ -0,0 +1,148 @@ +/** + * Session journal entry shapes. Every `ask_user` form, draft and outcome is + * appended to the session as a custom entry (never model context), so the + * state of any form can be rebuilt by replaying the active branch. + * + * Entries are append-only and versioned; `replayJournal` ignores anything it + * does not recognise, so new kinds can be added without breaking old sessions. + */ +import type { AskQuestion, AskResult, AskStateAnswer } from "../types.ts"; + +/** `customType` of every journal entry (`pi.appendEntry`). */ +export const ASK_JOURNAL_ENTRY_TYPE = "pi-ask:journal"; +/** `customType` of the follow-up message that carries a late answer. */ +export const ASK_ANSWER_MESSAGE_TYPE = "pi-ask:answer"; +export const ASK_JOURNAL_VERSION = 1; + +/** + * `foreground`: the tool call blocks on the form and returns its answer. + * `background`: the call returned a `queued` receipt; the form waits in the queue. + */ +export type AskFormMode = "foreground" | "background"; + +/** + * How an outcome reaches the agent. `tool`: it was the tool call's own result. + * `message`: the tool call is gone (or returned a receipt), so the outcome + * must be sent as a follow-up message and tracked with a `delivered` entry. + */ +export type AskOutcomeChannel = "tool" | "message"; + +/** The normalized form, enough to reopen it without the original call. */ +export interface AskFormSnapshot { + questions: AskQuestion[]; + timeoutSeconds?: number; + title?: string; +} + +/** In-progress answers of an open form. */ +export interface AskDraftSnapshot { + activeTabIndex?: number; + answers: Record; + /** Present only when the user changed a question's presented type. */ + questions?: AskQuestion[]; +} + +interface AskJournalEntryBase { + /** Epoch milliseconds. */ + at: number; + requestId: string; + v: typeof ASK_JOURNAL_VERSION; +} + +/** A valid call was accepted. Written before any waiting starts. */ +export interface AskFormEntry extends AskJournalEntryBase { + form: AskFormSnapshot; + kind: "form"; + mode: AskFormMode; + toolCallId?: string; +} + +/** Latest draft wins. */ +export interface AskDraftEntry extends AskJournalEntryBase { + draft: AskDraftSnapshot; + kind: "draft"; +} + +/** + * The user chose "answer later" on a foreground form: its tool call returned + * `deferred` and the form joined the queue in its original request order. + */ +export interface AskDeferEntry extends AskJournalEntryBase { + kind: "defer"; +} + +/** + * A form was resolved: `submitted`, `cancelled`, `expired` or `unavailable`. + * A later outcome for the same request supersedes it (late override of an + * expired form). Receipts (`queued`, `deferred`) are never outcomes. + */ +export interface AskOutcomeEntry extends AskJournalEntryBase { + channel: AskOutcomeChannel; + kind: "outcome"; + outcomeId: string; + result: AskResult; +} + +/** + * Exactly-once marker for a `message` outcome. Independent of queue state: + * it names the outcome, so a correction to an expired form is a new delivery. + */ +export interface AskDeliveredEntry extends AskJournalEntryBase { + kind: "delivered"; + outcomeId: string; +} + +export type AskJournalEntry = + | AskFormEntry + | AskDraftEntry + | AskDeferEntry + | AskOutcomeEntry + | AskDeliveredEntry; + +/** `details` of the follow-up message; also proves delivery on replay. */ +export interface AskAnswerMessageDetails { + outcomeId: string; + requestId: string; + result: AskResult; +} + +const ENTRY_KINDS = new Set(["form", "draft", "defer", "outcome", "delivered"]); + +/** Journal data from a session entry, or undefined if it is not usable. */ +export function parseJournalEntry(data: unknown): AskJournalEntry | undefined { + if (!isRecord(data)) { + return; + } + if ( + data.v !== ASK_JOURNAL_VERSION || + typeof data.requestId !== "string" || + typeof data.kind !== "string" || + !ENTRY_KINDS.has(data.kind) + ) { + return; + } + switch (data.kind) { + case "form": + return isRecord(data.form) && Array.isArray(data.form.questions) + ? (data as unknown as AskFormEntry) + : undefined; + case "draft": + return isRecord(data.draft) && isRecord(data.draft.answers) + ? (data as unknown as AskDraftEntry) + : undefined; + case "outcome": + return typeof data.outcomeId === "string" && isRecord(data.result) + ? (data as unknown as AskOutcomeEntry) + : undefined; + case "delivered": + return typeof data.outcomeId === "string" + ? (data as unknown as AskDeliveredEntry) + : undefined; + default: + return data as unknown as AskDeferEntry; + } +} + +export function isRecord(value: unknown): value is Record { + return !!value && typeof value === "object" && !Array.isArray(value); +} diff --git a/pi-ask/src/journal/journal.ts b/pi-ask/src/journal/journal.ts new file mode 100644 index 00000000..b0eb9716 --- /dev/null +++ b/pi-ask/src/journal/journal.ts @@ -0,0 +1,157 @@ +/** + * Journal writer and branch reader. The writer is the only place entries are + * created; `replay.ts` is the only place they are interpreted. + */ +import { randomUUID } from "node:crypto"; +import type { + ExtensionAPI, + ExtensionContext, +} from "@earendil-works/pi-coding-agent"; +import { draftContentKey, toDraftSnapshot } from "../state/draft.ts"; +import type { AskResult, AskState } from "../types.ts"; +import { + ASK_JOURNAL_ENTRY_TYPE, + ASK_JOURNAL_VERSION, + type AskDraftSnapshot, + type AskFormMode, + type AskFormSnapshot, + type AskJournalEntry, + type AskOutcomeChannel, + type AskOutcomeEntry, +} from "./entries.ts"; +import { type AskJournalState, replayJournal } from "./replay.ts"; + +export interface AskJournal { + /** + * Returns a callback for the open form's state changes. It appends a draft + * entry only when the answers change, never for cursor movement. + */ + draftRecorder( + requestId: string, + initial?: AskDraftSnapshot + ): (state: AskState) => void; + /** Marks a `message` outcome as having reached the agent. */ + recordDelivered(requestId: string, outcomeId: string): void; + /** A foreground form moved to the queue ("answer later"). */ + recordDefer(requestId: string): void; + /** Saves an accepted form and returns its new request id. */ + recordForm(input: { + form: AskFormSnapshot; + mode: AskFormMode; + toolCallId?: string; + }): string; + /** + * Saves a form's outcome. The returned entry's result carries the request + * id; return or deliver that result, not the one passed in. + */ + recordOutcome( + requestId: string, + result: AskResult, + channel: AskOutcomeChannel + ): AskOutcomeEntry; +} + +export interface AskJournalDeps { + newId?: () => string; + now?: () => number; +} + +type DistributiveOmit = T extends unknown + ? Omit + : never; + +export function createAskJournal( + append: (entry: AskJournalEntry) => void, + deps: AskJournalDeps = {} +): AskJournal { + const now = deps.now ?? Date.now; + const newId = deps.newId ?? shortId; + const write = (entry: DistributiveOmit) => { + const full = { ...entry, v: ASK_JOURNAL_VERSION, at: now() }; + append(full as AskJournalEntry); + return full; + }; + + return { + recordForm({ form, mode, toolCallId }) { + const requestId = `ask-${newId()}`; + write({ + kind: "form", + requestId, + mode, + form, + ...(toolCallId ? { toolCallId } : {}), + }); + return requestId; + }, + draftRecorder(requestId, initial) { + let lastKey = draftContentKey(initial ?? { answers: {} }); + return (state) => { + if (state.completed) { + return; + } + const draft = toDraftSnapshot(state); + const key = draftContentKey(draft); + if (key === lastKey) { + return; + } + lastKey = key; + write({ kind: "draft", requestId, draft }); + }; + }, + recordDefer(requestId) { + write({ kind: "defer", requestId }); + }, + recordOutcome(requestId, result, channel) { + return write({ + kind: "outcome", + requestId, + outcomeId: newId(), + channel, + result: { ...result, requestId }, + }) as AskOutcomeEntry; + }, + recordDelivered(requestId, outcomeId) { + write({ kind: "delivered", requestId, outcomeId }); + }, + }; +} + +/** + * Journal backed by the session file. Writing is best-effort: a host without + * `appendEntry`, or a failed write, must not stop the user being asked. + */ +export function createSessionAskJournal( + pi: Pick, + deps?: AskJournalDeps +): AskJournal { + return createAskJournal((entry) => { + try { + pi.appendEntry?.(ASK_JOURNAL_ENTRY_TYPE, entry); + } catch { + // Losing recovery data is better than losing the question. + } + }, deps); +} + +/** Journal state of the active branch only. */ +export function readAskJournal( + ctx: Pick +): AskJournalState { + return replayJournal(ctx.sessionManager.getBranch()); +} + +export function toFormSnapshot( + state: Pick, + timeoutSeconds?: number +): AskFormSnapshot { + return { + ...(state.title ? { title: state.title } : {}), + questions: structuredClone(state.questions), + ...(timeoutSeconds === undefined ? {} : { timeoutSeconds }), + }; +} + +function shortId(): string { + return randomUUID().replace(/-/g, "").slice(0, 8); +} diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts new file mode 100644 index 00000000..68c2afcb --- /dev/null +++ b/pi-ask/src/journal/replay.ts @@ -0,0 +1,200 @@ +/** + * Pure replay of the journal: branch entries in, form records out. Callers + * pass the ACTIVE branch (`ctx.sessionManager.getBranch()`), never the whole + * file, so a form asked on a sibling branch does not exist here. + */ +import { + ASK_ANSWER_MESSAGE_TYPE, + ASK_JOURNAL_ENTRY_TYPE, + type AskDraftSnapshot, + type AskFormMode, + type AskFormSnapshot, + type AskOutcomeEntry, + isRecord, + parseJournalEntry, +} from "./entries.ts"; + +/** The parts of a Pi `SessionEntry` the replay reads. */ +export interface BranchEntryLike { + customType?: string; + data?: unknown; + details?: unknown; + message?: unknown; + type: string; +} + +export interface AskJournalRecord { + createdAt: number; + /** A foreground form the user sent to the queue with "answer later". */ + deferred: boolean; + /** Outcome ids that already reached the agent as a follow-up message. */ + delivered: ReadonlySet; + draft?: AskDraftSnapshot; + form: AskFormSnapshot; + mode: AskFormMode; + /** Latest outcome; undefined while the form is still open. */ + outcome?: AskOutcomeEntry; + requestId: string; + /** + * A user or assistant message landed on the branch while the form was + * still open. For a blocking foreground form that means the conversation + * went on without it. + */ + supersededByMessage: boolean; + toolCallId?: string; +} + +export interface AskJournalState { + /** In request order. */ + records: AskJournalRecord[]; +} + +interface MutableRecord extends AskJournalRecord { + delivered: Set; +} + +export function replayJournal( + entries: readonly BranchEntryLike[] +): AskJournalState { + const records = new Map(); + const deliveredOutcomeIds = new Map(); + + for (const entry of entries) { + if (entry.type === "custom_message") { + noteAnswerMessage(entry, deliveredOutcomeIds); + continue; + } + if (entry.type === "message") { + if (isConversationMessage(entry.message)) { + for (const record of records.values()) { + if (!record.outcome) { + record.supersededByMessage = true; + } + } + } + continue; + } + if (entry.type !== "custom" || entry.customType !== ASK_JOURNAL_ENTRY_TYPE) { + continue; + } + const journalEntry = parseJournalEntry(entry.data); + if (!journalEntry) { + continue; + } + if (journalEntry.kind === "form") { + if (!records.has(journalEntry.requestId)) { + records.set(journalEntry.requestId, { + requestId: journalEntry.requestId, + createdAt: journalEntry.at, + mode: journalEntry.mode === "background" ? "background" : "foreground", + form: journalEntry.form, + toolCallId: journalEntry.toolCallId, + deferred: false, + delivered: new Set(), + supersededByMessage: false, + }); + } + continue; + } + // Anything about a form this branch never asked is ignored. + const record = records.get(journalEntry.requestId); + if (!record) { + continue; + } + switch (journalEntry.kind) { + case "draft": + record.draft = journalEntry.draft; + break; + case "defer": + record.deferred = true; + break; + case "outcome": + record.outcome = journalEntry; + break; + case "delivered": + deliveredOutcomeIds.set(journalEntry.outcomeId, journalEntry.requestId); + break; + default: + break; + } + } + + for (const [outcomeId, requestId] of deliveredOutcomeIds) { + records.get(requestId)?.delivered.add(outcomeId); + } + return { records: [...records.values()] }; +} + +export function getRecord( + state: AskJournalState, + requestId: string +): AskJournalRecord | undefined { + return state.records.find((record) => record.requestId === requestId); +} + +/** Still waiting for its first outcome. */ +export function isOpen(record: AskJournalRecord): boolean { + return !record.outcome; +} + +/** + * Foreground forms whose tool call ended without an outcome (Pi quit or + * crashed mid-form) and that the conversation has not moved past. + */ +export function interruptedForms(state: AskJournalState): AskJournalRecord[] { + return state.records.filter( + (record) => + isOpen(record) && + record.mode === "foreground" && + !record.deferred && + !record.supersededByMessage + ); +} + +/** Background and deferred forms awaiting an answer, first asked first. */ +export function queuedForms(state: AskJournalState): AskJournalRecord[] { + return state.records.filter( + (record) => + isOpen(record) && (record.mode === "background" || record.deferred) + ); +} + +/** Expired forms: resolved by fallback, still open to a late correction. */ +export function reopenableForms(state: AskJournalState): AskJournalRecord[] { + return state.records.filter( + (record) => record.outcome?.result.status === "expired" + ); +} + +/** Records whose latest outcome still has to be sent as a follow-up. */ +export function undeliveredOutcomes( + state: AskJournalState +): Array { + return state.records.filter( + (record): record is AskJournalRecord & { outcome: AskOutcomeEntry } => + !!record.outcome && + record.outcome.channel === "message" && + !record.delivered.has(record.outcome.outcomeId) + ); +} + +/** A persisted answer message proves delivery even if its marker is missing. */ +function noteAnswerMessage( + entry: BranchEntryLike, + deliveredOutcomeIds: Map +) { + if (entry.customType !== ASK_ANSWER_MESSAGE_TYPE || !isRecord(entry.details)) { + return; + } + const { outcomeId, requestId } = entry.details; + if (typeof outcomeId === "string" && typeof requestId === "string") { + deliveredOutcomeIds.set(outcomeId, requestId); + } +} + +function isConversationMessage(message: unknown): boolean { + return ( + isRecord(message) && + (message.role === "user" || message.role === "assistant") + ); +} diff --git a/pi-ask/src/state/draft.ts b/pi-ask/src/state/draft.ts new file mode 100644 index 00000000..2a09db36 --- /dev/null +++ b/pi-ask/src/state/draft.ts @@ -0,0 +1,57 @@ +import type { AskDraftSnapshot } from "../journal/entries.ts"; +import type { AskState } from "../types.ts"; +import { navigateView, submitView } from "./view.ts"; + +/** What must survive a restart for an open form to continue where it was. */ +export function toDraftSnapshot(state: AskState): AskDraftSnapshot { + const typeChanged = state.questions.some( + (question) => question.presentedType !== undefined + ); + return { + answers: structuredClone(state.answers), + activeTabIndex: state.activeTabIndex, + ...(typeChanged ? { questions: structuredClone(state.questions) } : {}), + }; +} + +/** + * Restore a draft onto a freshly created state. Answers for questions the + * form does not have are dropped; a question list that no longer lines up + * with the form is ignored. + */ +export function applyDraftSnapshot( + state: AskState, + draft: AskDraftSnapshot | undefined +): AskState { + if (!draft) { + return state; + } + const ids = state.questions.map((question) => question.id); + const questions = + draft.questions?.length === ids.length && + draft.questions.every((question, index) => question.id === ids[index]) + ? structuredClone(draft.questions) + : state.questions; + const answers = Object.fromEntries( + Object.entries(draft.answers).filter(([questionId]) => + ids.includes(questionId) + ) + ); + const tab = draft.activeTabIndex; + const activeTabIndex = + typeof tab === "number" && Number.isInteger(tab) + ? Math.max(0, Math.min(tab, ids.length)) + : state.activeTabIndex; + return { + ...state, + questions, + answers: structuredClone(answers), + activeTabIndex, + view: activeTabIndex >= ids.length ? submitView() : navigateView(), + }; +} + +/** Changes in this key are worth a journal entry; cursor moves are not. */ +export function draftContentKey(draft: AskDraftSnapshot): string { + return JSON.stringify([draft.answers, draft.questions ?? null]); +} diff --git a/pi-ask/tests/draft.test.ts b/pi-ask/tests/draft.test.ts new file mode 100644 index 00000000..5c0b9634 --- /dev/null +++ b/pi-ask/tests/draft.test.ts @@ -0,0 +1,85 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createInitialState } from "../src/state/create.ts"; +import { + applyDraftSnapshot, + draftContentKey, + toDraftSnapshot, +} from "../src/state/draft.ts"; +import { moveTab } from "../src/state/navigation.ts"; +import { cycleCurrentQuestionType } from "../src/state/question-type.ts"; +import { toAskResult } from "../src/state/result.ts"; +import { + confirmCurrentSelection, + saveCustomAnswer, +} from "../src/state/transitions.ts"; + +const PARAMS = { + questions: [ + { + id: "db", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "sqlite", label: "SQLite" }, + ], + }, + { id: "why", prompt: "Why?", type: "text" as const }, + ], +}; + +test("a draft round-trips answers, position and JSON", () => { + let state = confirmCurrentSelection(createInitialState(PARAMS)); + state = saveCustomAnswer( + { ...state, view: { kind: "input", questionId: "why" } }, + "it is boring" + ); + const draft = JSON.parse(JSON.stringify(toDraftSnapshot(state))); + const restored = applyDraftSnapshot(createInitialState(PARAMS), draft); + + assert.deepEqual(restored.answers, JSON.parse(JSON.stringify(state.answers))); + assert.equal(restored.activeTabIndex, state.activeTabIndex); + assert.equal(restored.completed, false); + assert.deepEqual( + toAskResult(restored).answers, + toAskResult(state).answers + ); + assert.equal(draft.questions, undefined, "unchanged questions are not stored"); +}); + +test("a draft keeps a changed question type and the submit tab", () => { + let state = cycleCurrentQuestionType(createInitialState(PARAMS)).state; + state = moveTab(moveTab(state, 1), 1); + const restored = applyDraftSnapshot( + createInitialState(PARAMS), + toDraftSnapshot(state) + ); + assert.equal(restored.questions[0]?.type, "multi"); + assert.equal(restored.questions[0]?.presentedType, "multi"); + assert.equal(restored.view.kind, "submit"); +}); + +test("a draft that does not fit the form is applied conservatively", () => { + const fresh = createInitialState(PARAMS); + assert.equal(applyDraftSnapshot(fresh, undefined), fresh); + const restored = applyDraftSnapshot(fresh, { + answers: { ghost: { selected: [] } }, + activeTabIndex: 99, + questions: [], + }); + assert.deepEqual(restored.answers, {}); + assert.equal(restored.activeTabIndex, 2); + assert.deepEqual(restored.questions, fresh.questions); +}); + +test("the draft content key ignores cursor position", () => { + const state = createInitialState(PARAMS); + assert.equal( + draftContentKey(toDraftSnapshot(state)), + draftContentKey(toDraftSnapshot(moveTab(state, 1))) + ); + assert.notEqual( + draftContentKey(toDraftSnapshot(state)), + draftContentKey(toDraftSnapshot(confirmCurrentSelection(state))) + ); +}); diff --git a/pi-ask/tests/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts new file mode 100644 index 00000000..cc288c8a --- /dev/null +++ b/pi-ask/tests/journal-replay.test.ts @@ -0,0 +1,247 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { + ASK_ANSWER_MESSAGE_TYPE, + ASK_JOURNAL_ENTRY_TYPE, + type AskJournalEntry, +} from "../src/journal/entries.ts"; +import { createAskJournal, toFormSnapshot } from "../src/journal/journal.ts"; +import { + type BranchEntryLike, + getRecord, + interruptedForms, + queuedForms, + reopenableForms, + replayJournal, + undeliveredOutcomes, +} from "../src/journal/replay.ts"; +import { createInitialState } from "../src/state/create.ts"; +import { toAskResult } from "../src/state/result.ts"; +import { confirmCurrentSelection } from "../src/state/transitions.ts"; +import type { AskResult, AskResultStatus } from "../src/types.ts"; + +const PARAMS = { + title: "Storage", + questions: [ + { + id: "db", + label: "DB", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "sqlite", label: "SQLite" }, + ], + }, + ], +}; + +/** A branch under construction plus a journal that appends to it. */ +function branch() { + const entries: BranchEntryLike[] = []; + let id = 0; + const journal = createAskJournal( + (entry: AskJournalEntry) => + entries.push({ + type: "custom", + customType: ASK_JOURNAL_ENTRY_TYPE, + data: structuredClone(entry), + }), + { now: () => 1000 + entries.length, newId: () => String(++id) } + ); + const form = (mode: "foreground" | "background" = "foreground") => + journal.recordForm({ + mode, + form: toFormSnapshot(createInitialState(PARAMS)), + toolCallId: "call-1", + }); + const message = (role: string) => + entries.push({ type: "message", message: { role } }); + return { entries, journal, form, message }; +} + +function result(status: AskResultStatus = "submitted"): AskResult { + const state = confirmCurrentSelection(createInitialState(PARAMS)); + return toAskResult(state, status); +} + +test("a form with no outcome is an interrupted foreground form", () => { + const b = branch(); + const requestId = b.form(); + const state = replayJournal(b.entries); + + assert.equal(requestId, "ask-1"); + assert.deepEqual( + interruptedForms(state).map((record) => record.requestId), + [requestId] + ); + assert.deepEqual(queuedForms(state), []); + const record = getRecord(state, requestId); + assert.equal(record?.form.title, "Storage"); + assert.equal(record?.form.questions[0]?.id, "db"); + assert.equal(record?.toolCallId, "call-1"); +}); + +test("the latest draft wins and survives replay", () => { + const b = branch(); + const requestId = b.form(); + const record = b.journal.draftRecorder(requestId); + const initial = createInitialState(PARAMS); + record(initial); + record({ ...initial, activeTabIndex: 1 }); + assert.equal(b.entries.length, 1, "cursor moves are not journalled"); + + const answered = confirmCurrentSelection(initial); + record({ ...answered, completed: false }); + record({ ...answered, completed: false }); + assert.equal(b.entries.length, 2, "an unchanged draft is not rewritten"); + + const draft = getRecord(replayJournal(b.entries), requestId)?.draft; + assert.deepEqual(draft?.answers.db?.selected[0]?.value, "pg"); +}); + +test("a tool outcome completes the form and needs no delivery", () => { + const b = branch(); + const requestId = b.form(); + const outcome = b.journal.recordOutcome(requestId, result(), "tool"); + const state = replayJournal(b.entries); + + assert.equal(outcome.result.requestId, requestId); + assert.deepEqual(interruptedForms(state), []); + assert.deepEqual(undeliveredOutcomes(state), []); + assert.equal(getRecord(state, requestId)?.outcome?.result.status, "submitted"); +}); + +test("a message outcome stays undelivered until its marker is written", () => { + const b = branch(); + const requestId = b.form(); + const outcome = b.journal.recordOutcome(requestId, result(), "message"); + assert.deepEqual( + undeliveredOutcomes(replayJournal(b.entries)).map((r) => r.requestId), + [requestId] + ); + + b.journal.recordDelivered(requestId, outcome.outcomeId); + assert.deepEqual(undeliveredOutcomes(replayJournal(b.entries)), []); +}); + +test("a persisted answer message proves delivery without a marker", () => { + const b = branch(); + const requestId = b.form(); + const outcome = b.journal.recordOutcome(requestId, result(), "message"); + b.entries.push({ + type: "custom_message", + customType: ASK_ANSWER_MESSAGE_TYPE, + details: { requestId, outcomeId: outcome.outcomeId }, + }); + assert.deepEqual(undeliveredOutcomes(replayJournal(b.entries)), []); +}); + +test("delivery is tracked per outcome, so a late correction is delivered again", () => { + const b = branch(); + const requestId = b.form("background"); + const expired = b.journal.recordOutcome( + requestId, + result("expired"), + "message" + ); + b.journal.recordDelivered(requestId, expired.outcomeId); + let state = replayJournal(b.entries); + assert.deepEqual(undeliveredOutcomes(state), []); + assert.deepEqual( + reopenableForms(state).map((record) => record.requestId), + [requestId] + ); + assert.deepEqual(queuedForms(state), [], "an expired form left the queue"); + + const correction = b.journal.recordOutcome(requestId, result(), "message"); + state = replayJournal(b.entries); + assert.equal( + undeliveredOutcomes(state)[0]?.outcome.outcomeId, + correction.outcomeId + ); + assert.deepEqual(reopenableForms(state), []); +}); + +test("the queue is first asked first, and a deferred form keeps its place", () => { + const b = branch(); + const first = b.form("foreground"); + const second = b.form("background"); + const third = b.form("background"); + b.journal.recordDefer(first); + b.message("assistant"); + + let state = replayJournal(b.entries); + assert.deepEqual( + queuedForms(state).map((record) => record.requestId), + [first, second, third] + ); + assert.deepEqual( + interruptedForms(state), + [], + "deferred and background forms are never interrupted foreground forms" + ); + + b.journal.recordOutcome(second, result("cancelled"), "message"); + state = replayJournal(b.entries); + assert.deepEqual( + queuedForms(state).map((record) => record.requestId), + [first, third] + ); +}); + +test("a foreground form the conversation moved past is not interrupted", () => { + const b = branch(); + b.form(); + b.message("toolResult"); + assert.equal(interruptedForms(replayJournal(b.entries)).length, 1); + + b.message("user"); + assert.deepEqual(interruptedForms(replayJournal(b.entries)), []); +}); + +test("replay ignores foreign, malformed and orphaned entries", () => { + const b = branch(); + const requestId = b.form(); + const entries: BranchEntryLike[] = [ + { type: "custom", customType: "other-extension", data: { kind: "form" } }, + { type: "custom", customType: ASK_JOURNAL_ENTRY_TYPE }, + { type: "custom", customType: ASK_JOURNAL_ENTRY_TYPE, data: "nope" }, + { + type: "custom", + customType: ASK_JOURNAL_ENTRY_TYPE, + data: { v: 99, kind: "form", requestId: "ask-future", form: {} }, + }, + { + type: "custom", + customType: ASK_JOURNAL_ENTRY_TYPE, + data: { v: 1, kind: "teleport", requestId }, + }, + // An outcome whose form lives on another branch. + { + type: "custom", + customType: ASK_JOURNAL_ENTRY_TYPE, + data: { + v: 1, + at: 1, + kind: "outcome", + requestId: "ask-elsewhere", + outcomeId: "x", + channel: "message", + result: result(), + }, + }, + { type: "custom_message", customType: ASK_ANSWER_MESSAGE_TYPE }, + ...b.entries, + // A second form entry with the same id never replaces the first. + { + ...b.entries[0], + data: { ...(b.entries[0]?.data as object), mode: "background" }, + } as BranchEntryLike, + ]; + const state = replayJournal(entries); + assert.deepEqual( + state.records.map((record) => [record.requestId, record.mode]), + [[requestId, "foreground"]] + ); + assert.deepEqual(undeliveredOutcomes(state), []); +}); From 3c18c616b5beed995193f799d8e4fcea5b9b842c Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:15:48 +0000 Subject: [PATCH 05/38] feat(ask): journal forms and recover interrupted ones Every valid ask_user call saves its form before waiting, its drafts as answers change and its outcome before returning. In TUI mode a foreground form left open when Pi stopped reopens with its draft on session start or tree navigation; the answer goes to the agent as a follow-up message exactly once, tracked per outcome on the active branch. --- pi-ask/src/ask-tool-helpers.ts | 7 +- pi-ask/src/ask-tool.ts | 39 +++- pi-ask/src/delivery.ts | 72 +++++++ pi-ask/src/i18n.ts | 20 ++ pi-ask/src/index.ts | 6 +- pi-ask/src/recovery.ts | 195 +++++++++++++++++++ pi-ask/src/runtime.ts | 18 ++ pi-ask/src/ui/controller.ts | 22 ++- pi-ask/tests/recovery.test.ts | 324 ++++++++++++++++++++++++++++++++ pi-ask/tests/support/fake-pi.ts | 140 ++++++++++++++ scripts/packages.mjs | 3 +- 11 files changed, 830 insertions(+), 16 deletions(-) create mode 100644 pi-ask/src/delivery.ts create mode 100644 pi-ask/src/recovery.ts create mode 100644 pi-ask/src/runtime.ts create mode 100644 pi-ask/tests/recovery.test.ts create mode 100644 pi-ask/tests/support/fake-pi.ts diff --git a/pi-ask/src/ask-tool-helpers.ts b/pi-ask/src/ask-tool-helpers.ts index 62c9dca2..06fe120b 100644 --- a/pi-ask/src/ask-tool-helpers.ts +++ b/pi-ask/src/ask-tool-helpers.ts @@ -48,15 +48,14 @@ export function invalidPayloadResponse( } export function nonInteractiveResponse( - state: ReturnType + state: ReturnType, + details: AskResult = toAskResult(state, "unavailable") ) { return { content: [ { type: "text" as const, text: formatNonInteractiveMessage(state) }, ], - details: { - ...toAskResult(state, "unavailable"), - }, + details, }; } diff --git a/pi-ask/src/ask-tool.ts b/pi-ask/src/ask-tool.ts index 8050731d..a291226a 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -14,18 +14,24 @@ import { } from "./ask-tool-helpers.ts"; import { type AskFeatures, NO_ASK_FEATURES } from "./features.ts"; import { buildAskParamsSchema, stripSchemaDescriptions } from "./schema.ts"; +import { toFormSnapshot } from "./journal/journal.ts"; +import { type AskRuntime, createAskRuntime } from "./runtime.ts"; import { prepareAskParams } from "./state/normalize.ts"; -import type { AskParams } from "./types.ts"; +import { toAskResult } from "./state/result.ts"; +import type { AskParams, AskResult } from "./types.ts"; import { runAskFlow } from "./ui/controller.ts"; import { runRpcAskFlow } from "./ui/rpc-flow.ts"; export interface AskToolOptions { /** Optional schema fields to register; see `resolveAskFeatures`. */ features?: AskFeatures; + /** Journal and live-form registry; shared with recovery when given. */ + runtime?: AskRuntime; } export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) { const features = options.features ?? NO_ASK_FEATURES; + const runtime = options.runtime ?? createAskRuntime(pi); pi.registerTool({ name: "ask_user", label: "Ask User", @@ -36,14 +42,16 @@ export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) // Field prose lives in the guidelines; the registered schema stays lean. parameters: stripSchemaDescriptions(buildAskParamsSchema(features)), prepareArguments: (args) => prepareAskParams(args) as AskParams, - execute: (_toolCallId, params, signal, _onUpdate, ctx) => - executeAskTool(params as AskParams, ctx, signal), + execute: (toolCallId, params, signal, _onUpdate, ctx) => + executeAskTool(runtime, toolCallId, params as AskParams, ctx, signal), renderCall: renderAskToolCall, renderResult: renderAskToolResult, }); } async function executeAskTool( + { journal, live }: AskRuntime, + toolCallId: string, params: AskParams, ctx: ExtensionContext, signal?: AbortSignal @@ -52,20 +60,37 @@ async function executeAskTool( if (!validation.ok) { return invalidPayloadResponse(params, validation.issues); } + // Journalled before any waiting, so a form that never returns can be + // recovered; the outcome is journalled before the tool returns. + const requestId = journal.recordForm({ + mode: "foreground", + form: toFormSnapshot(validation.state, params.timeoutSeconds), + toolCallId, + }); + const settle = (result: AskResult) => + journal.recordOutcome(requestId, result, "tool").result; + if (ctx.mode !== "tui") { // Hosts with dialog UI but no custom TUI (RPC subagents, ACP clients) // get the card-based fallback; print/json keeps the pending summary. if (ctx.hasUI) { const result = await runRpcAskFlow(ctx.ui, validation.state, signal); - return successfulResponse(result); + return successfulResponse(settle(result)); } - return nonInteractiveResponse(validation.state); + return nonInteractiveResponse( + validation.state, + settle(toAskResult(validation.state, "unavailable")) + ); } ctx.ui.setWorkingVisible(false); + live.add(requestId); try { - const result = await runAskFlow(ctx, params); - return successfulResponse(result); + const result = await runAskFlow(ctx, params, { + onStateChange: journal.draftRecorder(requestId), + }); + return successfulResponse(settle(result)); } finally { + live.delete(requestId); ctx.ui.setWorkingVisible(true); } } diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts new file mode 100644 index 00000000..1e5f371e --- /dev/null +++ b/pi-ask/src/delivery.ts @@ -0,0 +1,72 @@ +/** + * Sends a journalled outcome to the agent as a follow-up message. Used when + * the tool call that asked is no longer waiting (recovered, deferred or + * background forms). Exactly-once is the journal's job: callers pass only + * records from `undeliveredOutcomes`, and the marker is written here. + */ +import type { + ExtensionAPI, + ExtensionContext, +} from "@earendil-works/pi-coding-agent"; +import { askStrings } from "./i18n.ts"; +import { + ASK_ANSWER_MESSAGE_TYPE, + type AskAnswerMessageDetails, + type AskOutcomeEntry, +} from "./journal/entries.ts"; +import type { AskJournal } from "./journal/journal.ts"; +import { summarizeResult } from "./state/result.ts"; +import type { AskResult } from "./types.ts"; + +type SendOptions = Parameters[1]; + +/** Model-facing text of the follow-up message. */ +export function formatDeliveredOutcome(result: AskResult): string { + const requestId = result.requestId ?? ""; + if (result.status === "cancelled") { + return askStrings().cancelDelivered(requestId, result.title); + } + return [ + askStrings().answerDelivered(requestId, result.title), + summarizeResult(result), + ].join("\n"); +} + +/** + * An answer wakes an idle agent and joins a working one at the next turn + * boundary. A cancellation is added as context but never starts a turn. + */ +export function deliveryOptions( + result: AskResult, + idle: boolean +): SendOptions { + if (result.status === "cancelled") { + return { triggerTurn: false }; + } + return idle ? { triggerTurn: true } : { triggerTurn: true, deliverAs: "steer" }; +} + +export function deliverAskOutcome( + pi: Pick, + ctx: Pick, + journal: AskJournal, + outcome: AskOutcomeEntry +): void { + const details: AskAnswerMessageDetails = { + requestId: outcome.requestId, + outcomeId: outcome.outcomeId, + result: outcome.result, + }; + // Send first: if it throws, no marker is written and it is retried on + // the next replay. The persisted message also proves delivery by itself. + pi.sendMessage( + { + customType: ASK_ANSWER_MESSAGE_TYPE, + content: formatDeliveredOutcome(outcome.result), + display: true, + details, + }, + deliveryOptions(outcome.result, ctx.isIdle()) + ); + journal.recordDelivered(outcome.requestId, outcome.outcomeId); +} diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index 8f230532..e2d66a51 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -35,6 +35,12 @@ export interface AskStrings { deferredSummary: (requestId: string) => string; /** Trailer returned to the model after the time limit lapsed. */ expiredSummary: (fallbackLabels: string[]) => string; + /** Heading of the follow-up message that carries a late answer. */ + answerDelivered: (requestId: string, title?: string) => string; + /** Follow-up message for a form cancelled after its tool call ended. */ + cancelDelivered: (requestId: string, title?: string) => string; + /** Shown to the user when an interrupted form reopens. */ + recoveredNotice: string; /** Short transcript labels for the non-answer statuses. */ queuedLabel: string; deferredLabel: string; @@ -46,6 +52,10 @@ const EN_RECEIPT_RULES = const ZH_RECEIPT_RULES = "这只是回执,不是回答,也不是批准。只继续不依赖该回答的工作;回答会在之后的消息中送达。不要重复提问。"; +function formRef(requestId: string, title?: string): string { + return title ? `${requestId} (${title})` : requestId; +} + const EN_STRINGS: AskStrings = { backTo: (label) => `← Back to ${label}`, done: (count) => `✔ Done (${count} selected)`, @@ -71,6 +81,11 @@ const EN_STRINGS: AskStrings = { : "No fallback was applied.", "A fallback is your own assumption, not user approval; keep irreversible actions blocked. The user may still correct it.", ].join(" "), + answerDelivered: (requestId, title) => + `User answered your earlier ask_user form ${formRef(requestId, title)}:`, + cancelDelivered: (requestId, title) => + `User cancelled your earlier ask_user form ${formRef(requestId, title)}. Cancellation is not approval; keep risky actions blocked.`, + recoveredNotice: "Reopened a question left unanswered when Pi last stopped", queuedLabel: "Queued", deferredLabel: "Answer later", expiredLabel: "Expired", @@ -100,6 +115,11 @@ const ZH_STRINGS: AskStrings = { : "没有应用任何备选项。", "备选项只是你自己的假设,不是用户批准;不可逆的操作仍须保持阻止。用户之后仍可更正。", ].join(""), + answerDelivered: (requestId, title) => + `用户回答了你之前的 ask_user 表单 ${formRef(requestId, title)}:`, + cancelDelivered: (requestId, title) => + `用户取消了你之前的 ask_user 表单 ${formRef(requestId, title)}。取消不代表批准;有风险的操作仍须保持阻止。`, + recoveredNotice: "已重新打开上次 Pi 停止时未回答的问题", queuedLabel: "已排队", deferredLabel: "稍后回答", expiredLabel: "已超时", diff --git a/pi-ask/src/index.ts b/pi-ask/src/index.ts index e8a661a4..4897632a 100644 --- a/pi-ask/src/index.ts +++ b/pi-ask/src/index.ts @@ -4,13 +4,17 @@ import { registerAskSettingsCommand } from "./ask-settings-command.ts"; import { registerAskTool } from "./ask-tool.ts"; import { getAskConfigStore, resetAskConfigStore } from "./config/store.ts"; import { resolveAskFeatures } from "./features.ts"; +import { registerAskRecovery } from "./recovery.ts"; +import { createAskRuntime } from "./runtime.ts"; export default async function askExtension(pi: ExtensionAPI) { resetAskConfigStore(); // Schema-shaping settings are fixed here, so toggling them takes a reload // and never invalidates the prompt cache mid-session. const features = resolveAskFeatures(await getAskConfigStore().peek()); - registerAskTool(pi, { features }); + const runtime = createAskRuntime(pi); + registerAskTool(pi, { features, runtime }); + registerAskRecovery(pi, runtime); registerAskSettingsCommand(pi); registerAnswerCommands(pi); } diff --git a/pi-ask/src/recovery.ts b/pi-ask/src/recovery.ts new file mode 100644 index 00000000..1c8d518e --- /dev/null +++ b/pi-ask/src/recovery.ts @@ -0,0 +1,195 @@ +/** + * Interrupted-form recovery. A foreground form that was open when Pi quit or + * crashed has a form entry and no outcome on the active branch. In TUI mode + * it is reopened with its draft; the original tool call's promise is gone, + * so the result goes to the agent as a follow-up message. + */ +import type { + ExtensionAPI, + ExtensionContext, +} from "@earendil-works/pi-coding-agent"; +import { deliverAskOutcome } from "./delivery.ts"; +import { askStrings } from "./i18n.ts"; +import type { AskFormSnapshot } from "./journal/entries.ts"; +import { readAskJournal } from "./journal/journal.ts"; +import { + getRecord, + interruptedForms, + isOpen, + undeliveredOutcomes, +} from "./journal/replay.ts"; +import type { AskRuntime } from "./runtime.ts"; +import type { AskParams } from "./types.ts"; +import { runAskFlow } from "./ui/controller.ts"; + +export interface AskRecoveryDeps { + /** Runs `task` after the current lifecycle dispatch has finished. */ + defer?: (task: () => void) => void; + runFlow?: typeof runAskFlow; +} + +export interface AskRecovery { + /** Stop for good: the session this runtime belongs to is going away. */ + dispose(): void; + /** Check the active branch; returns at once, never waits for a form. */ + schedule(ctx: ExtensionContext): void; + /** Resolves when no recovery work is in flight. For tests. */ + settled(): Promise; +} + +export function registerAskRecovery( + pi: ExtensionAPI, + runtime: AskRuntime, + deps: AskRecoveryDeps = {} +): AskRecovery { + const recovery = createAskRecovery(pi, runtime, deps); + // Handlers only schedule: an open form must not hold up Pi's lifecycle. + pi.on("session_start", (_event, ctx) => recovery.schedule(ctx)); + pi.on("session_tree", (_event, ctx) => recovery.schedule(ctx)); + pi.on("session_shutdown", () => recovery.dispose()); + return recovery; +} + +export function createAskRecovery( + pi: Pick, + { journal, live }: AskRuntime, + deps: AskRecoveryDeps = {} +): AskRecovery { + const defer = deps.defer ?? ((task) => setTimeout(task, 0)); + const runFlow = deps.runFlow ?? runAskFlow; + // Guards for one process, on top of the journal: a form is offered once, + // and an outcome is sent once, even if a journal write was lost. + const offered = new Set(); + const sent = new Set(); + // The recovered form on screen. `detached` once its branch is no longer + // the active one: from then on nothing about it is written. + let open: { detached: boolean; requestId: string } | undefined; + let ctx: ExtensionContext | undefined; + let disposed = false; + let work: Promise | undefined; + let again = false; + + function deliverPending(current: ExtensionContext) { + for (const { outcome } of undeliveredOutcomes(readAskJournal(current))) { + if (sent.has(outcome.outcomeId)) { + continue; + } + sent.add(outcome.outcomeId); + deliverAskOutcome(pi, current, journal, outcome); + } + } + + async function recoverNext(current: ExtensionContext): Promise { + const record = interruptedForms(readAskJournal(current)).find( + ({ requestId }) => !(offered.has(requestId) || live.has(requestId)) + ); + if (!record) { + return false; + } + const { requestId } = record; + offered.add(requestId); + live.add(requestId); + const form = { requestId, detached: false }; + const recordDraft = journal.draftRecorder(requestId, record.draft); + let result: Awaited>; + open = form; + try { + current.ui.notify(askStrings().recoveredNotice, "info"); + result = await runFlow(current, formToParams(record.form), { + draft: record.draft, + onStateChange(state) { + if (!(disposed || form.detached)) { + recordDraft(state); + } + }, + }); + } finally { + open = undefined; + live.delete(requestId); + } + if (disposed) { + return false; + } + // The branch may have changed while the form was open. An answer is + // only written to a branch that still has the form and no outcome. + const latest = getRecord(readAskJournal(ctx ?? current), requestId); + if ( + form.detached || + !(latest && isOpen(latest)) || + result.status === "unavailable" + ) { + return true; + } + const outcome = journal.recordOutcome(requestId, result, "message"); + sent.add(outcome.outcomeId); + deliverAskOutcome(pi, ctx ?? current, journal, outcome); + return true; + } + + async function run() { + do { + again = false; + const current = ctx; + if (disposed || !current) { + return; + } + try { + deliverPending(current); + while (await recoverNext(current)) { + // One form at a time, in request order. + } + } catch { + // A stale context or a UI that failed to open: give up quietly. + // Unanswered forms stay in the journal for the next start. + } + } while (again); + } + + return { + schedule(next) { + if (disposed || next.mode !== "tui") { + return; + } + ctx = next; + if (open && !isOnBranch(next, open.requestId)) { + open.detached = true; + } + if (work) { + again = true; + return; + } + work = new Promise((resolve) => defer(resolve)) + .then(run) + .finally(() => { + work = undefined; + }); + }, + dispose() { + disposed = true; + ctx = undefined; + }, + async settled() { + while (work) { + await work; + } + }, + }; +} + +function isOnBranch(ctx: ExtensionContext, requestId: string): boolean { + try { + return !!getRecord(readAskJournal(ctx), requestId); + } catch { + return false; + } +} + +function formToParams(form: AskFormSnapshot): AskParams { + return { + title: form.title, + questions: form.questions, + ...(form.timeoutSeconds === undefined + ? {} + : { timeoutSeconds: form.timeoutSeconds }), + }; +} diff --git a/pi-ask/src/runtime.ts b/pi-ask/src/runtime.ts new file mode 100644 index 00000000..89b1a3ff --- /dev/null +++ b/pi-ask/src/runtime.ts @@ -0,0 +1,18 @@ +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import { type AskJournal, createSessionAskJournal } from "./journal/journal.ts"; + +/** State shared by the tool and the lifecycle handlers of one extension load. */ +export interface AskRuntime { + journal: AskJournal; + /** + * Request ids whose form is on screen in this process. Recovery skips + * them: an open form is not an interrupted one. + */ + live: Set; +} + +export function createAskRuntime( + pi: Pick +): AskRuntime { + return { journal: createSessionAskJournal(pi), live: new Set() }; +} diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 37775a00..4c761c7b 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -6,7 +6,9 @@ import { createQuestionWaitingNotification, notifyQuestionWaiting, } from "../notifications.ts"; +import type { AskDraftSnapshot } from "../journal/entries.ts"; import { createInitialState } from "../state/create.ts"; +import { applyDraftSnapshot } from "../state/draft.ts"; import { getEditorDraft, saveEditorDraft, @@ -59,18 +61,27 @@ type Theme = CustomCallbackArgs[1]; type Keybindings = CustomCallbackArgs[2]; type Done = (result: AskResult) => void; type AskFlowParams = AskParams & - Pick & { + Pick & + AskFlowOptions & { config: AskConfig; configNotice?: string; ctx: ExtensionContext; }; +export interface AskFlowOptions { + /** Answers to restore, e.g. from the journal of an interrupted form. */ + draft?: AskDraftSnapshot; + /** Called after every state change while the form is open. */ + onStateChange?: (state: AskState) => void; +} + interface AskFlowController { config: AskConfig; configNotice?: string; ctx: ExtensionContext; done: Done; editor: Editor; + onStateChange?: (state: AskState) => void; pendingDiscardConfirm: boolean; pendingQuestionTypeChangeQuestionId?: string; pendingReviewShortcutActionIndex?: number; @@ -85,7 +96,8 @@ interface AskFlowController { export async function runAskFlow( ctx: ExtensionContext, - params: AskParams + params: AskParams, + options: AskFlowOptions = {} ): Promise { const store = getAskConfigStore(); const { config, notice } = await store.ensureLoaded(); @@ -95,6 +107,7 @@ export async function runAskFlow( return ctx.ui.custom((...args) => createAskFlowController(args, { ...params, + ...options, config, configNotice: notice?.text, cwd: ctx.cwd, @@ -118,8 +131,9 @@ function createAskFlowController( ctx: params.ctx, done, editor: createEditor(tui, theme, params.cwd), + onStateChange: params.onStateChange, settingsOpen: false, - state: createInitialState(params), + state: applyDraftSnapshot(createInitialState(params), params.draft), suppressAutoInputForSelection: false, pendingDiscardConfirm: false, pendingQuestionTypeChangeQuestionId: undefined, @@ -528,6 +542,8 @@ function showSettingsModal(controller: AskFlowController) { } function refresh(controller: AskFlowController) { + // Every state change ends in a refresh, so this is the one observation point. + controller.onStateChange?.(controller.state); controller.tui.requestRender(); } diff --git a/pi-ask/tests/recovery.test.ts b/pi-ask/tests/recovery.test.ts new file mode 100644 index 00000000..92feb5fd --- /dev/null +++ b/pi-ask/tests/recovery.test.ts @@ -0,0 +1,324 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; +import { registerAskRecovery } from "../src/recovery.ts"; +import { createAskRuntime } from "../src/runtime.ts"; +import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; + +const PARAMS = { + title: "Storage", + questions: [ + { + id: "db", + label: "DB", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "sqlite", label: "SQLite" }, + ], + }, + { + id: "cache", + label: "Cache", + prompt: "Which cache?", + options: [ + { value: "redis", label: "Redis" }, + { value: "none", label: "None" }, + ], + }, + ], +}; + +/** One Pi process: the extension wired as `src/index.ts` wires it. */ +function boot(session?: SessionManager, options?: { mode?: string }) { + const host = fakePi(session, options); + const runtime = createAskRuntime(host.pi); + registerAskTool(host.pi, { runtime }); + const recovery = registerAskRecovery(host.pi, runtime); + const ask = () => + host.tools[0].execute("call-1", PARAMS, undefined, () => {}, host.ctx); + return { ...host, recovery, ask }; +} + +/** A session whose foreground form was open, DB answered, when Pi died. */ +async function interruptedSession() { + const first = boot(); + first.ask().catch(() => {}); + await tick(); + first.forms[0]?.press(KEY.enter); + assert.deepEqual( + first.journal().map((entry) => entry.kind), + ["form", "draft"] + ); + return first.session; +} + +async function start(host: ReturnType, reason = "resume") { + host.emit("session_start", { reason }); + await tick(); +} + +function kinds(host: ReturnType) { + return host.journal().map((entry) => entry.kind); +} + +beforeEach(quietConfig); + +test("a tool call journals the form before waiting and the outcome before returning", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + assert.deepEqual(kinds(host), ["form"]); + assert.equal(host.journal()[0].mode, "foreground"); + assert.equal(host.journal()[0].toolCallId, "call-1"); + + host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); + const response = await pending; + const outcome = host.journal().at(-1); + assert.equal(outcome.kind, "outcome"); + assert.equal(outcome.channel, "tool"); + assert.equal(response.details.status, "submitted"); + assert.equal(response.details.requestId, host.journal()[0].requestId); + assert.deepEqual(outcome.result, response.details); + + // Nothing is left to recover and nothing is sent twice. + await start(host, "reload"); + assert.equal(host.forms.length, 1); + assert.deepEqual(host.sent, []); +}); + +test("non-interactive and dialog hosts journal a settled outcome", async () => { + const host = boot(undefined, { mode: "json" }); + const response = await host.tools[0].execute( + "call-1", + PARAMS, + undefined, + () => {}, + { mode: "json", hasUI: false } + ); + assert.equal(response.details.status, "unavailable"); + assert.deepEqual(kinds(host), ["form", "outcome"]); + assert.equal(response.details.requestId, host.journal()[0].requestId); +}); + +test("an interrupted form reopens with its draft and its answer reaches the agent once", async () => { + const session = await interruptedSession(); + const host = boot(session); + const returned = host.emit("session_start", { reason: "resume" }); + assert.deepEqual( + returned, + [undefined], + "the handler returns at once instead of waiting for the form" + ); + await tick(); + assert.equal(host.forms.length, 1); + assert.equal(host.notices.length, 1); + assert.equal(host.sent.length, 0, "nothing is delivered while open"); + + // DB came back from the draft; only Cache and the review tab remain. + host.forms[0]?.press(KEY.enter, KEY.enter); + await tick(); + + assert.equal(host.sent.length, 1); + const [{ message, options }] = host.sent; + assert.equal(message.customType, ASK_ANSWER_MESSAGE_TYPE); + assert.deepEqual(options, { triggerTurn: true }); + assert.match(message.content, /ask-[0-9a-f]{8} \(Storage\)/); + assert.match(message.content, /DB: Postgres\nCache: Redis/); + assert.equal(message.details.result.status, "submitted"); + assert.deepEqual(kinds(host), [ + "form", + "draft", + "draft", + "outcome", + "delivered", + ]); + assert.equal(host.journal().at(-2).channel, "message"); +}); + +test("no duplicate delivery after a second session_start", async () => { + const session = await interruptedSession(); + const host = boot(session); + await start(host); + host.forms[0]?.press(KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + + await start(host, "reload"); + host.emit("session_tree"); + await tick(); + assert.equal(host.forms.length, 1); + assert.equal(host.sent.length, 1); + + // A later process on the same session sees the marker too. + const later = boot(session); + await start(later); + assert.equal(later.forms.length, 0); + assert.deepEqual(later.sent, []); +}); + +test("the delivery marker alone prevents a second delivery", async () => { + const session = await interruptedSession(); + // A working agent queues the message, so it is not in the session yet. + const host = fakePi(session, { persistSentMessages: false }); + const runtime = createAskRuntime(host.pi); + registerAskRecovery(host.pi, runtime); + host.setIdle(false); + host.emit("session_start", { reason: "resume" }); + await tick(); + host.forms[0]?.press(KEY.enter, KEY.enter); + await tick(); + assert.deepEqual(host.sent[0]?.options, { + triggerTurn: true, + deliverAs: "steer", + }); + + const later = boot(session); + await start(later); + assert.equal(later.forms.length, 0); + assert.deepEqual(later.sent, []); +}); + +test("an outcome journalled but never sent is delivered on the next start, once", async () => { + const session = await interruptedSession(); + const dying = fakePi(session); + const requestId = dying.journal()[0].requestId; + createAskRuntime(dying.pi).journal.recordOutcome( + requestId, + { + status: "submitted", + title: "Storage", + questions: [], + answers: {}, + unanswered: [], + }, + "message" + ); + + const host = boot(session); + await start(host); + await start(host, "reload"); + assert.equal(host.forms.length, 0, "an answered form is not reopened"); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, requestId); +}); + +test("a cancelled recovery is recorded, never wakes the agent and does not reopen", async () => { + const session = await interruptedSession(); + const host = boot(session); + await start(host); + // The restored draft makes the form dirty: cancel asks to confirm. + host.forms[0]?.press(KEY.escape, KEY.escape); + await tick(); + + assert.equal(host.sent.length, 1); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: false }); + assert.match(host.sent[0]?.message.content ?? "", /cancelled/); + assert.match(host.sent[0]?.message.content ?? "", /not approval/); + assert.equal(host.journal().at(-2).result.status, "cancelled"); + + await start(host, "reload"); + const later = boot(session); + await start(later); + assert.equal(host.forms.length, 1); + assert.equal(later.forms.length, 0); + assert.equal(later.sent.length, 0); +}); + +test("a stale form from another branch is ignored", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + // Branch A: a form interrupted mid-answer. + const first = boot(session); + first.ask().catch(() => {}); + await tick(); + first.forms[0]?.press(KEY.enter); + assert.equal(first.journal().length, 2); + + // Branch B forks from before the form was asked. + session.branch(rootId); + session.appendMessage({ role: "user", content: "other", timestamp: Date.now() }); + const host = boot(session); + await start(host); + host.emit("session_tree"); + await tick(); + assert.equal(host.forms.length, 0); + assert.deepEqual(host.sent, []); + assert.deepEqual(host.journal(), []); +}); + +test("an answer is dropped when the branch changes while the form is open", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + const first = boot(session); + first.ask().catch(() => {}); + await tick(); + + const host = boot(session); + await start(host); + assert.equal(host.forms.length, 1); + + session.branch(rootId); + host.emit("session_tree"); + host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); + await tick(); + + assert.deepEqual(host.sent, []); + assert.deepEqual( + host.journal(), + [], + "nothing from the other branch's form is written into this one" + ); +}); + +test("a form the conversation moved past is not reopened", async () => { + const session = await interruptedSession(); + session.appendMessage({ role: "user", content: "never mind", timestamp: Date.now() }); + const host = boot(session); + await start(host); + assert.equal(host.forms.length, 0); + assert.deepEqual(host.sent, []); +}); + +test("a form that is open in this process is not treated as interrupted", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + host.emit("session_tree"); + await start(host, "reload"); + assert.equal(host.forms.length, 1); + + host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); + assert.equal((await pending).details.status, "submitted"); + assert.deepEqual(host.sent, []); +}); + +test("recovery is TUI-only and stops at session shutdown", async () => { + const session = await interruptedSession(); + const rpc = boot(session, { mode: "rpc" }); + await start(rpc); + assert.equal(rpc.forms.length, 0); + assert.deepEqual(rpc.sent, []); + + const host = boot(session); + await start(host); + assert.equal(host.forms.length, 1); + host.emit("session_shutdown", { reason: "quit" }); + host.forms[0]?.press(KEY.enter, KEY.enter); + await tick(); + assert.deepEqual(host.sent, [], "a torn-down runtime writes nothing"); + assert.deepEqual(kinds(host), ["form", "draft"]); + + await start(host); + assert.equal(host.forms.length, 1); +}); diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts new file mode 100644 index 00000000..7b9ea328 --- /dev/null +++ b/pi-ask/tests/support/fake-pi.ts @@ -0,0 +1,140 @@ +/** + * A fake Pi host for lifecycle tests: a real in-memory SessionManager (so + * branches behave as they do in Pi), recorded sendMessage calls, and a + * `ui.custom` that exposes the open form for scripted key presses. + */ +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { DEFAULT_ASK_CONFIG } from "../../src/config/defaults.ts"; +import { getAskConfigStore } from "../../src/config/store.ts"; +import { ASK_JOURNAL_ENTRY_TYPE } from "../../src/journal/entries.ts"; +import type { AskResult } from "../../src/types.ts"; + +export const KEY = { enter: "\r", escape: "\u001b" }; + +export interface OpenForm { + done: (result: AskResult) => void; + press: (...keys: string[]) => void; +} + +export interface SentMessage { + message: { + content: string; + customType: string; + details?: any; + display: boolean; + }; + options?: { deliverAs?: string; triggerTurn?: boolean }; +} + +export function quietConfig() { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { ...DEFAULT_ASK_CONFIG.notifications, enabled: false }, + }); +} + +/** One extension runtime ("process") attached to a session. */ +export function fakePi( + session: SessionManager = SessionManager.inMemory(), + options: { mode?: string; persistSentMessages?: boolean } = {} +) { + const handlers = new Map unknown>>(); + const tools: any[] = []; + const sent: SentMessage[] = []; + const forms: OpenForm[] = []; + const notices: string[] = []; + let idle = true; + + const pi = { + on(event: string, handler: (...args: any[]) => unknown) { + handlers.set(event, [...(handlers.get(event) ?? []), handler]); + return () => {}; + }, + registerTool(tool: unknown) { + tools.push(tool); + }, + appendEntry(customType: string, data: unknown) { + session.appendCustomEntry(customType, structuredClone(data)); + }, + sendMessage(message: SentMessage["message"], sendOptions: any) { + sent.push({ message, options: sendOptions }); + if (options.persistSentMessages !== false) { + session.appendCustomMessageEntry( + message.customType, + message.content, + message.display, + structuredClone(message.details) + ); + } + }, + }; + + const ctx = { + cwd: process.cwd(), + mode: options.mode ?? "tui", + hasUI: true, + sessionManager: session, + isIdle: () => idle, + ui: { + notify(text: string) { + notices.push(text); + }, + setWorkingVisible() {}, + custom(factory: (...args: any[]) => any) { + return new Promise((resolve) => { + const tui = { requestRender() {} }; + const theme = { + bg: (_color: string, text: string) => text, + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + const component = factory(tui, theme, {}, resolve); + forms.push({ + done: resolve, + press: (...keys) => { + for (const key of keys) { + component.handleInput(key); + } + }, + }); + }); + }, + }, + }; + + return { + pi: pi as never, + ctx: ctx as never, + session, + sent, + forms, + notices, + tools, + setIdle(value: boolean) { + idle = value; + }, + /** Dispatch a lifecycle event; returns what the handlers returned. */ + emit(event: string, payload: Record = {}) { + return (handlers.get(event) ?? []).map((handler) => + handler({ type: event, ...payload }, ctx) + ); + }, + journal() { + return session + .getBranch() + .filter( + (entry: any) => + entry.type === "custom" && + entry.customType === ASK_JOURNAL_ENTRY_TYPE + ) + .map((entry: any) => entry.data); + }, + }; +} + +/** Let deferred work and awaited promises run. */ +export async function tick(times = 3) { + for (let index = 0; index < times; index++) { + await new Promise((resolve) => setTimeout(resolve, 0)); + } +} diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 25b8a74a..3faecd05 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,8 +2,9 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "recovery.test.ts"], commands: ["answer", "ask-settings"], tools: ["ask_user"], + hooks: ["session_start", "session_tree", "session_shutdown"], }, "pi-automode": { name: "@gagansd/pi-automode", tests: "tests", From 3090da0fcb5da68d0fcbf2881da765e7deb9ee10 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:15:49 +0000 Subject: [PATCH 06/38] docs(ask): describe the async contract and session journal --- pi-ask/README.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/pi-ask/README.md b/pi-ask/README.md index 3ebb6407..4f8b64c9 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -44,21 +44,40 @@ Hosts without the custom TUI (RPC subagents, ACP clients) get the same interview ## Contract -Input: `{ title?, questions: [{ id, label?, prompt, type: single\|multi\|text, options? }] }`. +Input: `{ title?, background?, timeoutSeconds?, questions: [{ id, label?, prompt, type: single\|multi\|text, options?, fallback? }] }`. - `text` questions have no options. - `single` / `multi` need real options. Do not invent filler. - Recommended options get a `description`. Never preselected. - Typed text is never merged into option `values`. +- `background: true` queues the form and returns a receipt at once. The answer arrives later as a message. +- `timeoutSeconds` is a time limit, counted from when the form is on screen. Any keypress stops it for good. +- `fallback` is the option `value` applied when the limit lapses. It must match an option. Never on `text`. No `fallback`, no answer. Output: -- `status`: `submitted` | `cancelled` | `unavailable` | `invalid` +- `status`: `submitted` | `cancelled` | `unavailable` | `invalid` | `queued` | `deferred` | `expired` - `answers[id]`: `{ values, labels, customText?, note?, optionNotes? }` - `unanswered: id[]` +- `requestId`: ties a receipt to the answer delivered later +- `expired: id[]`: answers that are auto-applied fallbacks + +`queued` (background call) and `deferred` (you chose "answer later") are receipts, not answers. `expired` means nobody responded: a fallback is the agent's assumption, never approval. The rules ride in those results, so they cost context only when they happen. + +Every form, draft and outcome is journalled in the session. A form left open when Pi quit reopens on startup, resume or fork with its draft, and its answer reaches the agent once. The journal follows the active branch. Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the current chat model unless `answer.extractionModels` is set. `PI_ASK_LOCALE=zh` localizes the dialog cards and result summaries (Simplified Chinese). +| Key | Default | Effect | +| --- | --- | --- | +| `expiry.enabled` | `true` | `false` drops `timeoutSeconds` and `fallback` from the schema | +| `expiry.minSeconds` | `30` | Shorter limits are raised to this floor | +| `behaviour.background` | `true` | `false` drops `background`; every call blocks | + +Schema settings apply on `/reload`, not live. A disabled field is absent from the schema, not ignored. + +> Unreleased: `background`, `timeoutSeconds`, `fallback` and the `queued` / `deferred` / `expired` statuses are the 0.2.0 contract and are not registered yet. + ## Context footprint Recurring model-facing contribution of `ask_user`, measured with `npm run tokens` (character proxy: `ceil(chars / 4)`, not provider billing): @@ -72,3 +91,5 @@ Recurring model-facing contribution of `ask_user`, measured with `npm run tokens | **total** | **1,502** | **376** | Field-level prose lives in the guidelines; the registered schema ships without `description` keys. + +A test holds the total to 450 with every optional field registered and 420 with expiry disabled. From b3d774a3411bdda6f41497e27e0da9cd96ceff25 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:02 +0000 Subject: [PATCH 07/38] feat(ask): add answer-later and panel-focus keymaps Two global actions, configurable like the rest: `later` (Ctrl+L) and `panelFocus` (Alt+A). The footer takes the surface a form is drawn on, so a blocking form can offer "answer later" and the panel can show hide, cancel-form and switch-to-input hints. A config file written before an action existed now keeps its bindings: the missing action takes its default, minus any key the user already bound, instead of the whole keymap falling back to defaults. An empty key list is an unbound action. --- pi-ask/src/config/schema.ts | 6 +++ pi-ask/src/constants/keymaps.ts | 82 ++++++++++++++++++++++++++---- pi-ask/src/ui/input.ts | 4 ++ pi-ask/src/ui/render-frame.ts | 33 ++++++------ pi-ask/src/ui/render.ts | 13 ++++- pi-ask/tests/input.test.ts | 21 ++++++++ pi-ask/tests/keymaps.test.ts | 89 +++++++++++++++++++++++++++++++++ 7 files changed, 224 insertions(+), 24 deletions(-) create mode 100644 pi-ask/tests/keymaps.test.ts diff --git a/pi-ask/src/config/schema.ts b/pi-ask/src/config/schema.ts index 774897fb..aeae11ae 100644 --- a/pi-ask/src/config/schema.ts +++ b/pi-ask/src/config/schema.ts @@ -24,6 +24,8 @@ const AskKeyBindingSchema = Type.Union([ const AskConfigKeymapsSchema = Type.Object({ global: Type.Object({ dismiss: Type.Optional(AskKeyBindingSchema), + later: Type.Optional(AskKeyBindingSchema), + panelFocus: Type.Optional(AskKeyBindingSchema), settings: Type.Optional(AskKeyBindingSchema), }), main: Type.Object({ @@ -114,6 +116,10 @@ export interface AskConfigKeymaps { }; global: { dismiss: string[]; + /** "Answer later": defer a blocking form, or hide the panel. */ + later: string[]; + /** Switch keyboard focus between the panel and the normal input. */ + panelFocus: string[]; settings: string[]; }; main: { diff --git a/pi-ask/src/constants/keymaps.ts b/pi-ask/src/constants/keymaps.ts index f3b7fe47..9d6beefc 100644 --- a/pi-ask/src/constants/keymaps.ts +++ b/pi-ask/src/constants/keymaps.ts @@ -90,6 +90,8 @@ export const DEFAULT_ASK_KEYMAPS: AskConfigKeymaps = { global: { dismiss: ["ctrl+c"], settings: ["?"], + later: ["ctrl+l"], + panelFocus: ["alt+a"], }, main: { confirm: ["enter"], @@ -131,6 +133,8 @@ const DESCRIPTIONS: Record> = { global: { dismiss: "Dismiss the active ask surface", settings: "Open ask settings", + later: "Answer later: defer a blocking form, or hide the panel", + panelFocus: "Switch keyboard focus between the question panel and the input", }, main: { confirm: "Confirm selection, continue, or submit", @@ -168,11 +172,12 @@ const DESCRIPTIONS: Record> = { }, }; +/** An unbound action (empty key list) has no hint. */ const footerHint = ( binding: AskKeyBinding, action: string, label = binding.label -) => `${label} ${action}`; +) => (label ? `${label} ${action}` : ""); const footerKeyIdLabel = (binding: AskKeyBinding) => binding.keys.join(" / "); @@ -289,9 +294,18 @@ export function getGlobalBindings( return getAskContextBindings(config, "global"); } +/** Where the form is drawn; decides which exits the footer offers. */ +export interface FooterSurface { + /** A blocking form that offers "answer later". */ + defer?: boolean; + /** The background panel: `focused` says where the keyboard is. */ + panel?: { focused: boolean }; +} + export function renderFooterKeymaps( config: AskConfig, - context: FooterKeymapContext + context: FooterKeymapContext, + surface: FooterSurface = {} ): string { const global = getGlobalBindings(config); const main = getAskContextBindings(config, "main"); @@ -338,7 +352,35 @@ export function renderFooterKeymaps( footerHint(global.settings, "settings"), ], }; - return ` ${hintsByContext[context].join(" · ")}`; + if (surface.panel && !surface.panel.focused) { + return ` ${[ + footerHint(global.panelFocus, "answer here"), + "typing goes to the input below", + ] + .filter(Boolean) + .join(" · ")}`; + } + const editing = context === "input" || context === "note"; + const hints = hintsByContext[context] + .map((hint) => { + // In the panel the cancel key only puts the panel away. + const cancelHint = + hint === footerHint(main.cancel, "cancel") || + hint === footerHint(main.cancel, "dismiss"); + return surface.panel && !editing && cancelHint + ? footerHint(main.cancel, "hide") + : hint; + }) + .concat( + surface.panel + ? [ + editing ? footerHint(global.later, "hide") : "", + footerHint(global.dismiss, "cancel form"), + footerHint(global.panelFocus, "input"), + ] + : [surface.defer ? footerHint(global.later, "answer later") : ""] + ); + return ` ${hints.filter(Boolean).join(" · ")}`; } export function renderSettingsFooterKeymaps(config: AskConfig): string { @@ -358,6 +400,7 @@ export function normalizeConfiguredKeymaps( } const normalized = {} as AskConfigKeymaps; + const taken = configuredKeys(candidate as Record); for (const context of Object.keys( DEFAULT_ASK_KEYMAPS ) as AskKeymapContext[]) { @@ -367,7 +410,8 @@ export function normalizeConfiguredKeymaps( } const contextResult = normalizeContextKeymaps( context, - rawContext as Record + rawContext as Record, + taken ); if (!contextResult.ok) { return contextResult; @@ -385,7 +429,8 @@ export function normalizeConfiguredKeymaps( function normalizeContextKeymaps( context: AskKeymapContext, - rawContext: Record + rawContext: Record, + taken: ReadonlySet ): | { ok: true; keymaps: Record } | { ok: false; error: string } { @@ -397,7 +442,12 @@ function normalizeContextKeymaps( for (const action of Object.keys(defaults)) { const rawValue = rawContext[action]; if (rawValue === undefined) { - return { ok: false, error: `Missing keymap for ${context}.${action}.` }; + // A config written before this action existed: take the default, + // minus any key the user already gave to something else. + normalized[action] = (defaults[action] ?? []).filter( + (key) => !taken.has(key) + ); + continue; } const parsed = normalizeBindingList(rawValue); if (!parsed.ok) { @@ -415,6 +465,23 @@ function normalizeContextKeymaps( : { ok: true, keymaps: normalized }; } +/** Every key the config binds explicitly, outside the settings modal. */ +function configuredKeys(candidate: Record): Set { + const keys = new Set(); + for (const [context, actions] of Object.entries(candidate)) { + if (context === "settingsModal" || !(actions && typeof actions === "object")) { + continue; + } + for (const rawValue of Object.values(actions)) { + const parsed = normalizeBindingList(rawValue); + for (const key of parsed.ok ? parsed.keys : []) { + keys.add(key); + } + } + } + return keys; +} + function normalizeBindingList( rawValue: unknown ): { ok: true; keys: string[] } | { ok: false; error: string } { @@ -422,9 +489,6 @@ function normalizeBindingList( if (!Array.isArray(rawKeys)) { return { ok: false, error: "binding must be a string or array of strings" }; } - if (rawKeys.length === 0) { - return { ok: false, error: "empty binding list" }; - } const keys: string[] = []; for (const rawKey of rawKeys) { if (typeof rawKey !== "string") { diff --git a/pi-ask/src/ui/input.ts b/pi-ask/src/ui/input.ts index a87deba3..79a3d280 100644 --- a/pi-ask/src/ui/input.ts +++ b/pi-ask/src/ui/input.ts @@ -20,6 +20,7 @@ export type AskInputCommand = | { kind: "cancel" } | { kind: "changeQuestionType" } | { kind: "dismiss" } + | { kind: "later" } | { kind: "showSettings" } | { kind: "numberShortcut"; digit: number } | { kind: "editMoveTab"; delta: 1 | -1 } @@ -39,6 +40,9 @@ export function getInputCommand( if (matchesBinding(data, global.dismiss)) { return { kind: "dismiss" }; } + if (matchesBinding(data, global.later)) { + return { kind: "later" }; + } if (matchesBinding(data, global.settings) && editingText.length === 0) { return { kind: "showSettings" }; } diff --git a/pi-ask/src/ui/render-frame.ts b/pi-ask/src/ui/render-frame.ts index 8ce5f02d..c13a6936 100644 --- a/pi-ask/src/ui/render-frame.ts +++ b/pi-ask/src/ui/render-frame.ts @@ -1,6 +1,10 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui"; import type { AskConfig } from "../config/schema.ts"; -import { renderFooterKeymaps } from "../constants/keymaps.ts"; +import { + type FooterKeymapContext, + type FooterSurface, + renderFooterKeymaps, +} from "../constants/keymaps.ts"; import { getCurrentQuestion, isQuestionAnswered, @@ -33,12 +37,13 @@ export function renderFrameFooter(args: { footerNotice?: string; lines: string[]; state: AskState; + surface?: FooterSurface; theme: Theme; width: number; }) { - const { config, footerNotice, lines, state, theme, width } = args; + const { config, footerNotice, lines, state, surface, theme, width } = args; const add = (text = "") => lines.push(truncateToWidth(text, width)); - const footer = renderFooter(config, state, width); + const footer = renderFooter(config, state, width, surface); const noticeLines = footerNotice ? wrapText(footerNotice, width) : []; if (noticeLines.length > 0 || footer.length > 0) { add(); @@ -188,26 +193,26 @@ function applyTabGrowth( function renderFooter( config: AskConfig, state: AskState, - width: number + width: number, + surface?: FooterSurface ): string[] { if (!config.behaviour.showFooterHints) { return []; } - let footer: string; + let context: FooterKeymapContext; if (state.view.kind === "input") { - footer = renderFooterKeymaps(config, "input"); + context = "input"; } else if (state.view.kind === "note") { - footer = renderFooterKeymaps(config, "note"); + context = "note"; } else if (isSubmitTab(state)) { - footer = renderFooterKeymaps(config, "submit"); + context = "submit"; } else { - const question = getCurrentQuestion(state); - footer = renderFooterKeymaps( - config, - question?.type === "multi" ? "multi" : "default" - ); + context = getCurrentQuestion(state)?.type === "multi" ? "multi" : "default"; } - return wrapDelimitedFooterHints(footer, width); + return wrapDelimitedFooterHints( + renderFooterKeymaps(config, context, surface), + width + ); } function wrapDelimitedFooterHints(footer: string, width: number): string[] { diff --git a/pi-ask/src/ui/render.ts b/pi-ask/src/ui/render.ts index 802a03c8..e13d67db 100644 --- a/pi-ask/src/ui/render.ts +++ b/pi-ask/src/ui/render.ts @@ -1,4 +1,5 @@ import type { AskConfig } from "../config/schema.ts"; +import type { FooterSurface } from "../constants/keymaps.ts"; import { getCurrentQuestion, getRenderableOptions, @@ -15,6 +16,7 @@ export function renderAskScreen(args: { footerNotice?: string; reviewShortcutHint?: string; state: AskState; + surface?: FooterSurface; theme: Theme; width: number; editor: QuestionRenderContext["editor"]; @@ -24,6 +26,7 @@ export function renderAskScreen(args: { footerNotice, reviewShortcutHint, state, + surface, theme, width, editor, @@ -48,6 +51,14 @@ export function renderAskScreen(args: { }); } - renderFrameFooter({ config, footerNotice, lines, state, theme, width }); + renderFrameFooter({ + config, + footerNotice, + lines, + state, + surface, + theme, + width, + }); return lines; } diff --git a/pi-ask/tests/input.test.ts b/pi-ask/tests/input.test.ts index 82fdcc50..c5a38b7a 100644 --- a/pi-ask/tests/input.test.ts +++ b/pi-ask/tests/input.test.ts @@ -427,3 +427,24 @@ test("custom configured note shortcuts are used at runtime", () => { kind: "openQuestionNote", }); }); + +test("the later key is a command in every view, even with text typed", () => { + const later = "\x0c"; + const navigation = createInitialState({ + questions: [ + { id: "q1", prompt: "Question?", options: [{ value: "a", label: "A" }] }, + ], + }); + assert.deepEqual(getInputCommand(navigation, DEFAULT_ASK_CONFIG, later), { + kind: "later", + }); + assert.deepEqual( + getInputCommand(inputState(), DEFAULT_ASK_CONFIG, later, "typed text"), + { kind: "later" } + ); + const unbound = structuredClone(DEFAULT_ASK_CONFIG); + unbound.keymaps.global.later = []; + assert.notDeepEqual(getInputCommand(navigation, unbound, later), { + kind: "later", + }); +}); diff --git a/pi-ask/tests/keymaps.test.ts b/pi-ask/tests/keymaps.test.ts new file mode 100644 index 00000000..e68916a4 --- /dev/null +++ b/pi-ask/tests/keymaps.test.ts @@ -0,0 +1,89 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { DEFAULT_ASK_CONFIG, normalizeAskConfig } from "../src/config/defaults.ts"; +import { + DEFAULT_ASK_KEYMAPS, + normalizeConfiguredKeymaps, + renderFooterKeymaps, +} from "../src/constants/keymaps.ts"; + +/** Keymaps as a config file written before the panel keys existed. */ +function legacyKeymaps() { + const keymaps = structuredClone(DEFAULT_ASK_KEYMAPS) as any; + delete keymaps.global.later; + delete keymaps.global.panelFocus; + return keymaps; +} + +test("the panel keys default to ctrl+l and alt+a", () => { + assert.deepEqual(DEFAULT_ASK_KEYMAPS.global.later, ["ctrl+l"]); + assert.deepEqual(DEFAULT_ASK_KEYMAPS.global.panelFocus, ["alt+a"]); +}); + +test("a config from before the panel keys keeps its bindings and gains the defaults", () => { + const keymaps = legacyKeymaps(); + keymaps.main.confirm = ["ctrl+y"]; + const config = normalizeAskConfig({ keymaps }); + assert.deepEqual(config.keymaps.main.confirm, ["ctrl+y"], "custom keys survive"); + assert.deepEqual(config.keymaps.global.later, ["ctrl+l"]); + assert.deepEqual(config.keymaps.global.panelFocus, ["alt+a"]); +}); + +test("a new default never takes a key the user already bound", () => { + const keymaps = legacyKeymaps(); + keymaps.main.optionNote = ["ctrl+l"]; + const result = normalizeConfiguredKeymaps(keymaps); + assert.ok(result.ok); + assert.deepEqual(result.keymaps.main.optionNote, ["ctrl+l"]); + assert.deepEqual(result.keymaps.global.later, [], "left unbound instead"); + assert.deepEqual(result.keymaps.global.panelFocus, ["alt+a"]); + // The unbound action round-trips and shows no footer hint. + const again = normalizeConfiguredKeymaps(result.keymaps); + assert.ok(again.ok); + assert.deepEqual(again.keymaps.global.later, []); + const config = { ...DEFAULT_ASK_CONFIG, keymaps: again.keymaps }; + assert.doesNotMatch( + renderFooterKeymaps(config, "default", { defer: true }), + /answer later/ + ); +}); + +test("the panel keys are configurable and still checked for conflicts", () => { + const keymaps = structuredClone(DEFAULT_ASK_KEYMAPS); + keymaps.global.panelFocus = ["f6"]; + keymaps.global.later = ["ctrl+b"]; + const result = normalizeConfiguredKeymaps(keymaps); + assert.ok(result.ok); + assert.deepEqual(result.keymaps.global.panelFocus, ["f6"]); + + keymaps.global.later = ["enter"]; + const conflict = normalizeConfiguredKeymaps(keymaps); + assert.equal(conflict.ok, false); +}); + +test("footer hints follow the surface the form is drawn on", () => { + const modal = renderFooterKeymaps(DEFAULT_ASK_CONFIG, "default"); + assert.match(modal, /Esc dismiss/); + assert.doesNotMatch(modal, /later|Alt\+A/); + + const deferrable = renderFooterKeymaps(DEFAULT_ASK_CONFIG, "default", { defer: true }); + assert.match(deferrable, /Esc dismiss/); + assert.match(deferrable, /Ctrl\+L answer later/); + + const panel = { panel: { focused: true } }; + for (const context of ["default", "multi", "submit"] as const) { + const hints = renderFooterKeymaps(DEFAULT_ASK_CONFIG, context, panel); + assert.match(hints, /Esc hide/); + assert.doesNotMatch(hints, /Esc (dismiss|cancel)/); + assert.match(hints, /Ctrl\+C cancel form/); + assert.match(hints, /Alt\+A input/); + } + const editing = renderFooterKeymaps(DEFAULT_ASK_CONFIG, "input", panel); + assert.match(editing, /Esc close/); + assert.match(editing, /Ctrl\+L hide/); + + assert.equal( + renderFooterKeymaps(DEFAULT_ASK_CONFIG, "default", { panel: { focused: false } }), + " Alt+A answer here · typing goes to the input below" + ); +}); From 23ea9809261c208d3a284e876581176d560d0621 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:09 +0000 Subject: [PATCH 08/38] feat(ask): journal panel visibility and order the panel queue A `panel` journal entry records that the user hid or reopened the background panel, so visibility follows the active branch like the forms do. `pendingForms` is the single queue the panel shows: queued and interrupted forms in request order, minus blocking forms that are on screen in this process. --- pi-ask/src/journal/entries.ts | 28 ++++++++++++++++-- pi-ask/src/journal/journal.ts | 11 ++++++- pi-ask/src/journal/replay.ts | 26 ++++++++++++++++- pi-ask/tests/journal-replay.test.ts | 45 +++++++++++++++++++++++++++++ 4 files changed, 105 insertions(+), 5 deletions(-) diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts index 54dea935..5717c988 100644 --- a/pi-ask/src/journal/entries.ts +++ b/pi-ask/src/journal/entries.ts @@ -1,7 +1,8 @@ /** * Session journal entry shapes. Every `ask_user` form, draft and outcome is * appended to the session as a custom entry (never model context), so the - * state of any form can be rebuilt by replaying the active branch. + * state of any form, and of the panel that shows them, can be rebuilt by + * replaying the active branch. * * Entries are append-only and versioned; `replayJournal` ignores anything it * does not recognise, so new kinds can be added without breaking old sessions. @@ -92,12 +93,22 @@ export interface AskDeliveredEntry extends AskJournalEntryBase { outcomeId: string; } +/** + * The user put the background panel away (`hidden: true`) or brought it + * back. Latest wins; `requestId` is the form that was showing, if any. + */ +export interface AskPanelEntry extends AskJournalEntryBase { + hidden: boolean; + kind: "panel"; +} + export type AskJournalEntry = | AskFormEntry | AskDraftEntry | AskDeferEntry | AskOutcomeEntry - | AskDeliveredEntry; + | AskDeliveredEntry + | AskPanelEntry; /** `details` of the follow-up message; also proves delivery on replay. */ export interface AskAnswerMessageDetails { @@ -106,7 +117,14 @@ export interface AskAnswerMessageDetails { result: AskResult; } -const ENTRY_KINDS = new Set(["form", "draft", "defer", "outcome", "delivered"]); +const ENTRY_KINDS = new Set([ + "form", + "draft", + "defer", + "outcome", + "delivered", + "panel", +]); /** Journal data from a session entry, or undefined if it is not usable. */ export function parseJournalEntry(data: unknown): AskJournalEntry | undefined { @@ -138,6 +156,10 @@ export function parseJournalEntry(data: unknown): AskJournalEntry | undefined { return typeof data.outcomeId === "string" ? (data as unknown as AskDeliveredEntry) : undefined; + case "panel": + return typeof data.hidden === "boolean" + ? (data as unknown as AskPanelEntry) + : undefined; default: return data as unknown as AskDeferEntry; } diff --git a/pi-ask/src/journal/journal.ts b/pi-ask/src/journal/journal.ts index b0eb9716..24893f7a 100644 --- a/pi-ask/src/journal/journal.ts +++ b/pi-ask/src/journal/journal.ts @@ -30,10 +30,16 @@ export interface AskJournal { requestId: string, initial?: AskDraftSnapshot ): (state: AskState) => void; - /** Marks a `message` outcome as having reached the agent. */ + /** + * Marks a `message` outcome as having reached the agent. Delivery does + * not write it: the answer message on the branch is the proof. Replay + * still honours it for a host that confirms delivery some other way. + */ recordDelivered(requestId: string, outcomeId: string): void; /** A foreground form moved to the queue ("answer later"). */ recordDefer(requestId: string): void; + /** The user hid or reopened the panel; `requestId` is the form shown. */ + recordPanel(hidden: boolean, requestId?: string): void; /** Saves an accepted form and returns its new request id. */ recordForm(input: { form: AskFormSnapshot; @@ -102,6 +108,9 @@ export function createAskJournal( recordDefer(requestId) { write({ kind: "defer", requestId }); }, + recordPanel(hidden, requestId = "") { + write({ kind: "panel", requestId, hidden }); + }, recordOutcome(requestId, result, channel) { return write({ kind: "outcome", diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts index 68c2afcb..2ce5d377 100644 --- a/pi-ask/src/journal/replay.ts +++ b/pi-ask/src/journal/replay.ts @@ -45,6 +45,8 @@ export interface AskJournalRecord { } export interface AskJournalState { + /** The user put the background panel away on this branch. */ + panelHidden: boolean; /** In request order. */ records: AskJournalRecord[]; } @@ -58,6 +60,7 @@ export function replayJournal( ): AskJournalState { const records = new Map(); const deliveredOutcomeIds = new Map(); + let panelHidden = false; for (const entry of entries) { if (entry.type === "custom_message") { @@ -81,6 +84,10 @@ export function replayJournal( if (!journalEntry) { continue; } + if (journalEntry.kind === "panel") { + panelHidden = journalEntry.hidden; + continue; + } if (journalEntry.kind === "form") { if (!records.has(journalEntry.requestId)) { records.set(journalEntry.requestId, { @@ -122,7 +129,7 @@ export function replayJournal( for (const [outcomeId, requestId] of deliveredOutcomeIds) { records.get(requestId)?.delivered.add(outcomeId); } - return { records: [...records.values()] }; + return { panelHidden, records: [...records.values()] }; } export function getRecord( @@ -159,6 +166,23 @@ export function queuedForms(state: AskJournalState): AskJournalRecord[] { ); } +/** + * Everything the background panel shows, first asked first: queued forms + * plus interrupted foreground forms. `live` are the blocking forms on screen + * in this process, which are open but not interrupted. + */ +export function pendingForms( + state: AskJournalState, + live: ReadonlySet = new Set() +): AskJournalRecord[] { + const waiting = new Set( + [...queuedForms(state), ...interruptedForms(state)] + .filter((record) => record.deferred || !live.has(record.requestId)) + .map((record) => record.requestId) + ); + return state.records.filter((record) => waiting.has(record.requestId)); +} + /** Expired forms: resolved by fallback, still open to a late correction. */ export function reopenableForms(state: AskJournalState): AskJournalRecord[] { return state.records.filter( diff --git a/pi-ask/tests/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts index cc288c8a..e6831fb0 100644 --- a/pi-ask/tests/journal-replay.test.ts +++ b/pi-ask/tests/journal-replay.test.ts @@ -10,6 +10,7 @@ import { type BranchEntryLike, getRecord, interruptedForms, + pendingForms, queuedForms, reopenableForms, replayJournal, @@ -245,3 +246,47 @@ test("replay ignores foreign, malformed and orphaned entries", () => { ); assert.deepEqual(undeliveredOutcomes(state), []); }); + +test("the panel queue merges queued and interrupted forms in request order", () => { + const b = branch(); + const interrupted = b.form(); + const background = b.form("background"); + const live = b.form(); + const deferred = b.form(); + b.journal.recordDefer(deferred); + const answered = b.form("background"); + b.journal.recordOutcome(answered, result("submitted"), "message"); + + const ids = (liveIds: string[] = []) => + pendingForms(replayJournal(b.entries), new Set(liveIds)).map( + (record) => record.requestId + ); + assert.deepEqual(ids(), [interrupted, background, live, deferred]); + // A blocking form on screen is open, not interrupted; once deferred it + // is queued even while its tool call is still unwinding. + assert.deepEqual(ids([live, deferred]), [interrupted, background, deferred]); + + // The conversation moving on drops interrupted forms, never queued ones. + b.message("user"); + assert.deepEqual(ids(), [background, deferred]); +}); + +test("panel visibility follows the latest panel entry on the branch", () => { + const b = branch(); + assert.equal(replayJournal(b.entries).panelHidden, false); + const requestId = b.form("background"); + b.journal.recordPanel(true, requestId); + assert.equal(replayJournal(b.entries).panelHidden, true); + // A sibling branch that ends before the entry never hid the panel. + assert.equal(replayJournal(b.entries.slice(0, 1)).panelHidden, false); + b.journal.recordPanel(false); + assert.equal(replayJournal(b.entries).panelHidden, false); + assert.equal(replayJournal(b.entries).records.length, 1, "not a form record"); + + const malformed = { + type: "custom", + customType: ASK_JOURNAL_ENTRY_TYPE, + data: { v: 1, kind: "panel", requestId: "", at: 1, hidden: "yes" }, + }; + assert.equal(replayJournal([...b.entries, malformed]).panelHidden, false); +}); From 73ee3fe31d69fd81f7b098fae75aa7d9f6244128 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:16 +0000 Subject: [PATCH 09/38] feat(ask): add pure panel ownership and delivery planning state/panel.ts decides which form the panel shows and who owns the keyboard: one form at a time in request order, a blocking form takes over and the panel returns as it was, a hidden panel never reopens or takes focus, a rebuild never takes focus. state/outbox.ts decides how an undelivered outcome is sent: proposed at a turn boundary while the agent works, a wake when it is idle, appended without a turn for cancellations and after an aborted run, and held while already on its way. --- pi-ask/src/state/outbox.ts | 92 +++++++++++++++++++++++ pi-ask/src/state/panel.ts | 123 +++++++++++++++++++++++++++++++ pi-ask/tests/panel-state.test.ts | 107 +++++++++++++++++++++++++++ 3 files changed, 322 insertions(+) create mode 100644 pi-ask/src/state/outbox.ts create mode 100644 pi-ask/src/state/panel.ts create mode 100644 pi-ask/tests/panel-state.test.ts diff --git a/pi-ask/src/state/outbox.ts b/pi-ask/src/state/outbox.ts new file mode 100644 index 00000000..72908594 --- /dev/null +++ b/pi-ask/src/state/outbox.ts @@ -0,0 +1,92 @@ +/** + * How a late outcome reaches the agent, as pure decisions. + * + * Whether an outcome HAS been delivered is never decided here: that is read + * from the session branch, where the answer message itself is the proof. This + * module only picks the next step for outcomes that are not there yet. + * + * - `propose`: the agent is working and a turn just ended. The answer is + * handed to Pi as a turn-boundary entry, so it joins the running work + * without an extra turn being started for it. + * - `wake`: the agent is idle; the answer starts a turn. + * - `append`: added to the conversation without starting a turn. Used for + * cancellations, and for anything left over after the user aborted the run: + * stopping the agent must not be undone by an answer. + * - `hold`: nothing to do yet. Either the outcome is already on its way, or + * the agent is busy and a turn boundary or settle will follow. + */ + +export type AskDeliveryAction = "propose" | "wake" | "append" | "hold"; + +/** + * `now`: an outcome was just recorded, or the session was (re)built. + * `boundary`: a turn ended, or the run is about to settle. + * `settled`: the run is over and Pi will not continue on its own. + */ +export type AskDeliveryTrigger = "now" | "boundary" | "settled"; + +export interface AskDeliveryItem { + /** A cancellation: recorded as context, never a reason to start a turn. */ + cancelled: boolean; + /** Already sent in this process and not yet seen on the branch. */ + inFlight: boolean; + outcomeId: string; +} + +export interface AskDeliverySituation { + /** The run that just settled was aborted by the user. */ + aborted?: boolean; + /** `ctx.isIdle()`; ignored for `boundary` and `settled`. */ + idle: boolean; + trigger: AskDeliveryTrigger; +} + +export interface AskDeliveryStep { + action: AskDeliveryAction; + outcomeId: string; +} + +/** One step per item, in the order given (request order). */ +export function planDelivery( + items: readonly AskDeliveryItem[], + situation: AskDeliverySituation +): AskDeliveryStep[] { + // A settled run is idle by definition, whatever the host still reports. + const idle = situation.trigger === "settled" || situation.idle; + let woken = false; + return items.map(({ cancelled, inFlight, outcomeId }) => { + const step = (action: AskDeliveryAction) => ({ outcomeId, action }); + if (inFlight) { + return step("hold"); + } + if (situation.trigger === "boundary") { + return step("propose"); + } + // Once one answer has woken the agent, the rest join at its first + // turn boundary instead of each starting a run. + if (!idle || woken) { + return step("hold"); + } + if (cancelled || situation.aborted) { + return step("append"); + } + woken = true; + return step("wake"); + }); +} + +/** + * Whether proposing at a boundary should also ask Pi for one more model + * request. Without it an answer that arrives during the final turn would sit + * in the conversation unseen. Cancellations never ask; neither does a turn + * the user aborted. + */ +export function boundaryContinues( + items: readonly Pick[], + turnStopReason?: string +): boolean { + if (turnStopReason === "aborted" || turnStopReason === "error") { + return false; + } + return items.some((item) => !item.cancelled); +} diff --git a/pi-ask/src/state/panel.ts b/pi-ask/src/state/panel.ts new file mode 100644 index 00000000..c153e43c --- /dev/null +++ b/pi-ask/src/state/panel.ts @@ -0,0 +1,123 @@ +/** + * Queue and keyboard ownership of the background panel, as pure state. + * + * The rules: + * - One form is shown at a time: the head of the queue, which is in request + * order across background, deferred and recovered forms. + * - A blocking (foreground) form owns the keyboard. While one is open the + * panel is off screen, so two forms never compete for input; it comes back + * with the focus it had. + * - A panel the user hid stays hidden, and unfocused, whatever arrives. + * - A new request takes focus only when it opens a panel that was not + * showing a form, and only if the caller allows it. + */ + +export interface AskPanelState { + /** Whether the keyboard should be in the panel when it is on screen. */ + focused: boolean; + /** Blocking forms currently open. */ + foreground: number; + /** The user put the panel away; only the user brings it back. */ + hidden: boolean; + /** Request ids waiting for an answer, first asked first. */ + queue: readonly string[]; +} + +export interface AskPanelView { + focused: boolean; + /** The one form the panel shows; undefined when the panel is off screen. */ + formId?: string; + visible: boolean; +} + +export type AskPanelEvent = + /** Rebuilt from the journal (start, reload, resume, fork, tree). */ + | { type: "sync"; queue: readonly string[]; hidden: boolean } + /** A request joined the queue in this process. */ + | { type: "arrived"; queue: readonly string[]; focus: boolean } + /** A form left the queue (answered, cancelled, or gone from the branch). */ + | { type: "removed"; queue: readonly string[] } + | { type: "hide" } + | { type: "reopen" } + | { type: "toggleFocus" } + /** The host moved the keyboard away from the panel. */ + | { type: "blurred" } + /** The host gave the keyboard back, e.g. when a dialog over it closed. */ + | { type: "refocused" } + | { type: "foregroundOpened" } + | { type: "foregroundClosed" }; + +export const EMPTY_PANEL: AskPanelState = { + queue: [], + hidden: false, + focused: false, + foreground: 0, +}; + +export function panelView(state: AskPanelState): AskPanelView { + const formId = state.queue[0]; + const visible = + formId !== undefined && !state.hidden && state.foreground === 0; + return visible + ? { visible, formId, focused: state.focused } + : { visible: false, focused: false }; +} + +/** Whether a toggle-focus key belongs to the panel right now. */ +export function panelTakesFocusKey(state: AskPanelState): boolean { + return state.queue.length > 0 && state.foreground === 0; +} + +export function reducePanel( + state: AskPanelState, + event: AskPanelEvent +): AskPanelState { + switch (event.type) { + case "sync": + // A rebuild is not a new request: it never takes the keyboard. + return { + ...state, + queue: event.queue, + hidden: event.hidden, + focused: false, + }; + case "arrived": { + const wasShowing = state.queue.length > 0; + return { + ...state, + queue: event.queue, + focused: + state.hidden || wasShowing ? state.focused : event.focus, + }; + } + case "removed": + return { + ...state, + queue: event.queue, + focused: event.queue.length > 0 && state.focused, + }; + case "hide": + return { ...state, hidden: true, focused: false }; + case "reopen": + return state.queue.length > 0 + ? { ...state, hidden: false, focused: true } + : state; + case "toggleFocus": + if (!panelTakesFocusKey(state)) { + return state; + } + return state.hidden + ? { ...state, hidden: false, focused: true } + : { ...state, focused: !state.focused }; + case "blurred": + return { ...state, focused: false }; + case "refocused": + return panelView(state).visible ? { ...state, focused: true } : state; + case "foregroundOpened": + return { ...state, foreground: state.foreground + 1 }; + case "foregroundClosed": + return { ...state, foreground: Math.max(0, state.foreground - 1) }; + default: + return state; + } +} diff --git a/pi-ask/tests/panel-state.test.ts b/pi-ask/tests/panel-state.test.ts new file mode 100644 index 00000000..97e92a80 --- /dev/null +++ b/pi-ask/tests/panel-state.test.ts @@ -0,0 +1,107 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { + type AskPanelEvent, + type AskPanelState, + EMPTY_PANEL, + panelTakesFocusKey, + panelView, + reducePanel, +} from "../src/state/panel.ts"; + +function run(events: AskPanelEvent[], from: AskPanelState = EMPTY_PANEL) { + return events.reduce(reducePanel, from); +} + +const arrive = (queue: string[], focus = true): AskPanelEvent => ({ + type: "arrived", + queue, + focus, +}); + +test("an empty queue shows nothing and owns no key", () => { + assert.deepEqual(panelView(EMPTY_PANEL), { visible: false, focused: false }); + assert.equal(panelTakesFocusKey(EMPTY_PANEL), false); + assert.equal(reducePanel(EMPTY_PANEL, { type: "toggleFocus" }), EMPTY_PANEL); + assert.equal(reducePanel(EMPTY_PANEL, { type: "reopen" }), EMPTY_PANEL); +}); + +test("only the head of the queue is shown, in request order", () => { + const state = run([arrive(["a"]), arrive(["a", "b"]), arrive(["a", "b", "c"])]); + assert.deepEqual(panelView(state), { visible: true, formId: "a", focused: true }); + const next = reducePanel(state, { type: "removed", queue: ["b", "c"] }); + assert.equal(panelView(next).formId, "b"); +}); + +test("a new request takes focus only when it opens the panel and is allowed to", () => { + assert.equal(panelView(run([arrive(["a"], true)])).focused, true); + assert.equal(panelView(run([arrive(["a"], false)])).focused, false); + // The panel already shows a form: its focus is the user's, either way. + const typing = run([arrive(["a"], false), arrive(["a", "b"], true)]); + assert.equal(panelView(typing).focused, false); + const answering = run([arrive(["a"], true), arrive(["a", "b"], false)]); + assert.equal(panelView(answering).focused, true); +}); + +test("a hidden panel does not reopen or take focus when a request arrives", () => { + const state = run([arrive(["a"]), { type: "hide" }, arrive(["a", "b"], true)]); + assert.deepEqual(panelView(state), { visible: false, focused: false }); + assert.equal(state.hidden, true); + assert.deepEqual(state.queue, ["a", "b"]); + // Only the user brings it back, by command or by the focus key. + assert.deepEqual(panelView(reducePanel(state, { type: "reopen" })), { + visible: true, + formId: "a", + focused: true, + }); + assert.deepEqual(panelView(reducePanel(state, { type: "toggleFocus" })), { + visible: true, + formId: "a", + focused: true, + }); +}); + +test("the focus key switches between the panel and the input", () => { + const focused = run([arrive(["a"])]); + const blurred = reducePanel(focused, { type: "toggleFocus" }); + assert.equal(panelView(blurred).focused, false); + assert.equal(panelView(blurred).visible, true); + assert.equal(panelView(reducePanel(blurred, { type: "toggleFocus" })).focused, true); +}); + +test("a rebuild restores the queue and visibility but never takes the keyboard", () => { + const focused = run([arrive(["a"])]); + const rebuilt = reducePanel(focused, { type: "sync", queue: ["a", "b"], hidden: false }); + assert.deepEqual(panelView(rebuilt), { visible: true, formId: "a", focused: false }); + const hidden = reducePanel(focused, { type: "sync", queue: ["a"], hidden: true }); + assert.equal(panelView(hidden).visible, false); +}); + +test("a blocking form owns the keyboard: the panel leaves and returns as it was", () => { + const focused = run([arrive(["a"])]); + const blocked = reducePanel(focused, { type: "foregroundOpened" }); + assert.deepEqual(panelView(blocked), { visible: false, focused: false }); + assert.equal(panelTakesFocusKey(blocked), false, "the focus key is not ours"); + assert.equal(reducePanel(blocked, { type: "toggleFocus" }), blocked); + // Requests that arrive meanwhile queue up behind the blocking form. + const queued = reducePanel(blocked, arrive(["a", "b"])); + assert.equal(panelView(queued).visible, false); + + const nested = run([{ type: "foregroundOpened" }, { type: "foregroundClosed" }], queued); + assert.equal(panelView(nested).visible, false, "one blocking form is still open"); + const back = reducePanel(nested, { type: "foregroundClosed" }); + assert.deepEqual(panelView(back), { visible: true, formId: "a", focused: true }); + assert.equal(reducePanel(back, { type: "foregroundClosed" }).foreground, 0); +}); + +test("focus the host took away stays away; an emptied queue holds none", () => { + const blurred = run([arrive(["a"]), { type: "blurred" }]); + assert.equal(panelView(blurred).focused, false); + // A dialog over the panel closed and the host handed the keyboard back. + assert.equal(panelView(reducePanel(blurred, { type: "refocused" })).focused, true); + const hidden = run([{ type: "hide" }, { type: "refocused" }], blurred); + assert.equal(hidden.focused, false, "an off-screen panel holds no focus"); + const emptied = run([arrive(["a"]), { type: "removed", queue: [] }]); + assert.equal(emptied.focused, false); + assert.deepEqual(panelView(emptied), { visible: false, focused: false }); +}); From 579c7d06d68a403165c6bda41104593b0be5daf7 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:43 +0000 Subject: [PATCH 10/38] feat(ask): queue forms in a non-modal panel with defer and late delivery Forms no tool call waits for share one queue, one panel and one way back to the agent: - The panel is a widget above Pi's editor. The editor keeps its text and stays usable; Alt+A moves the keyboard between the two, Esc or Ctrl+L hides the panel without cancelling, /ask-panel reopens it. A line under the editor counts unanswered questions, hidden ones included. - One form at a time in request order across background, deferred and recovered forms. A blocking call takes the keyboard while it is open and the panel returns afterwards as it was. A new request takes focus only when the input is empty; a hidden panel never reopens by itself. - Ctrl+L on a blocking form returns a `deferred` receipt and moves the form to the queue with its draft and its request-order place. - `background: true` journals the form and returns a `queued` receipt with the request id and pending count. Hosts without the TUI still block (card flow) or report `unavailable`. - Delivery is decided from the branch: an outcome is delivered when its pi-ask:answer message is there. A working agent gets it as a turn-boundary entry, an idle one is woken, a cancellation and anything left after an aborted run are appended without starting a turn. The message names the request and each question by id and prompt, and renders as a compact card. Interrupted-form recovery now goes through the same panel instead of a blocking form, so recovery.ts is gone. Queue, drafts and visibility are rebuilt from the active branch on start, reload, resume, fork and tree navigation; a form from another branch writes nothing. --- pi-ask/src/ask-tool.ts | 80 +++- pi-ask/src/background.ts | 513 ++++++++++++++++++++++ pi-ask/src/delivery.ts | 262 +++++++++-- pi-ask/src/i18n.ts | 68 ++- pi-ask/src/index.ts | 4 +- pi-ask/src/recovery.ts | 195 --------- pi-ask/src/runtime.ts | 10 +- pi-ask/src/state/result.ts | 2 +- pi-ask/src/types.ts | 2 + pi-ask/src/ui/controller.ts | 85 +++- pi-ask/src/ui/panel.ts | 260 +++++++++++ pi-ask/tests/background.test.ts | 751 ++++++++++++++++++++++++++++++++ pi-ask/tests/outbox.test.ts | 136 ++++++ pi-ask/tests/recovery.test.ts | 324 -------------- pi-ask/tests/support/fake-pi.ts | 277 ++++++++++-- scripts/packages.mjs | 6 +- 16 files changed, 2344 insertions(+), 631 deletions(-) create mode 100644 pi-ask/src/background.ts delete mode 100644 pi-ask/src/recovery.ts create mode 100644 pi-ask/src/ui/panel.ts create mode 100644 pi-ask/tests/background.test.ts create mode 100644 pi-ask/tests/outbox.test.ts delete mode 100644 pi-ask/tests/recovery.test.ts diff --git a/pi-ask/src/ask-tool.ts b/pi-ask/src/ask-tool.ts index a291226a..62d4b749 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -18,14 +18,14 @@ import { toFormSnapshot } from "./journal/journal.ts"; import { type AskRuntime, createAskRuntime } from "./runtime.ts"; import { prepareAskParams } from "./state/normalize.ts"; import { toAskResult } from "./state/result.ts"; -import type { AskParams, AskResult } from "./types.ts"; +import type { AskParams, AskResult, AskState } from "./types.ts"; import { runAskFlow } from "./ui/controller.ts"; import { runRpcAskFlow } from "./ui/rpc-flow.ts"; export interface AskToolOptions { /** Optional schema fields to register; see `resolveAskFeatures`. */ features?: AskFeatures; - /** Journal and live-form registry; shared with recovery when given. */ + /** Journal, live-form registry and queue; shared with the lifecycle. */ runtime?: AskRuntime; } @@ -43,14 +43,22 @@ export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) parameters: stripSchemaDescriptions(buildAskParamsSchema(features)), prepareArguments: (args) => prepareAskParams(args) as AskParams, execute: (toolCallId, params, signal, _onUpdate, ctx) => - executeAskTool(runtime, toolCallId, params as AskParams, ctx, signal), + executeAskTool( + runtime, + features, + toolCallId, + params as AskParams, + ctx, + signal + ), renderCall: renderAskToolCall, renderResult: renderAskToolResult, }); } async function executeAskTool( - { journal, live }: AskRuntime, + { background, journal, live }: AskRuntime, + features: AskFeatures, toolCallId: string, params: AskParams, ctx: ExtensionContext, @@ -60,19 +68,15 @@ async function executeAskTool( if (!validation.ok) { return invalidPayloadResponse(params, validation.issues); } - // Journalled before any waiting, so a form that never returns can be - // recovered; the outcome is journalled before the tool returns. - const requestId = journal.recordForm({ - mode: "foreground", - form: toFormSnapshot(validation.state, params.timeoutSeconds), - toolCallId, - }); - const settle = (result: AskResult) => - journal.recordOutcome(requestId, result, "tool").result; + const form = toFormSnapshot(validation.state, params.timeoutSeconds); if (ctx.mode !== "tui") { + // No persistent panel here, so `background` blocks like any other call. // Hosts with dialog UI but no custom TUI (RPC subagents, ACP clients) // get the card-based fallback; print/json keeps the pending summary. + const requestId = journal.recordForm({ mode: "foreground", form, toolCallId }); + const settle = (result: AskResult) => + journal.recordOutcome(requestId, result, "tool").result; if (ctx.hasUI) { const result = await runRpcAskFlow(ctx.ui, validation.state, signal); return successfulResponse(settle(result)); @@ -82,15 +86,57 @@ async function executeAskTool( settle(toAskResult(validation.state, "unavailable")) ); } + + // A stale call that still carries `background` after the feature was + // switched off blocks like any other call. + if (background && features.background && params.background === true) { + // Journalled first: the receipt promises an answer that survives a + // restart. No outcome is written; a receipt is not one. + const requestId = journal.recordForm({ mode: "background", form, toolCallId }); + const pending = background.enqueue(ctx, requestId, "background"); + return successfulResponse({ + ...receipt(validation.state, "queued", requestId), + pending, + }); + } + + // Journalled before any waiting, so a form that never returns can be + // recovered; the outcome is journalled before the tool returns. + const requestId = journal.recordForm({ mode: "foreground", form, toolCallId }); + const openForm = () => + runAskFlow(ctx, params, { + allowDefer: !!background, + onStateChange: journal.draftRecorder(requestId), + }); + let result: AskResult; ctx.ui.setWorkingVisible(false); live.add(requestId); try { - const result = await runAskFlow(ctx, params, { - onStateChange: journal.draftRecorder(requestId), - }); - return successfulResponse(settle(result)); + // A blocking form owns the keyboard: the panel steps aside for it. + result = await (background + ? background.foreground(ctx, openForm) + : openForm()); } finally { live.delete(requestId); ctx.ui.setWorkingVisible(true); } + if (background && result.status === "deferred") { + // "Answer later": the form keeps its request-order place in the queue + // and its draft; the answer follows as a message. + journal.recordDefer(requestId); + background.enqueue(ctx, requestId, "deferred"); + return successfulResponse(receipt(validation.state, "deferred", requestId)); + } + return successfulResponse( + journal.recordOutcome(requestId, result, "tool").result + ); +} + +/** A receipt names the form and carries no answers, not even drafted ones. */ +function receipt( + state: AskState, + status: "queued" | "deferred", + requestId: string +): AskResult { + return { ...toAskResult(state, status), requestId }; } diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts new file mode 100644 index 00000000..7b923583 --- /dev/null +++ b/pi-ask/src/background.ts @@ -0,0 +1,513 @@ +/** + * Forms whose tool call is not waiting for them: background calls, forms the + * user deferred, and forms left open when Pi last stopped. They share one + * queue in request order, one panel above the editor, and one way back to + * the agent (a follow-up message, see `delivery.ts`). + * + * Everything is rebuilt from the active session branch, so a reload, resume, + * fork or tree move shows exactly what that branch asked. This file is the + * wiring; the rules live in `state/panel.ts` and `state/outbox.ts`. + */ +import type { + ExtensionAPI, + ExtensionCommandContext, + ExtensionContext, +} from "@earendil-works/pi-coding-agent"; +import { isKeyRelease } from "@earendil-works/pi-tui"; +import { DEFAULT_ASK_CONFIG } from "./config/defaults.ts"; +import type { AskConfig } from "./config/schema.ts"; +import { getAskConfigStore } from "./config/store.ts"; +import { getGlobalBindings, matchesBinding } from "./constants/keymaps.ts"; +import { + type AskBoundaryEvent, + type AskBoundaryResult, + createAskDelivery, + renderAskAnswerMessage, +} from "./delivery.ts"; +import { askStrings } from "./i18n.ts"; +import { + ASK_ANSWER_MESSAGE_TYPE, + type AskFormSnapshot, +} from "./journal/entries.ts"; +import { readAskJournal } from "./journal/journal.ts"; +import { + type AskJournalRecord, + getRecord, + isOpen, + pendingForms, +} from "./journal/replay.ts"; +import type { AskRuntime } from "./runtime.ts"; +import { createInitialState } from "./state/create.ts"; +import { applyDraftSnapshot } from "./state/draft.ts"; +import { + type AskPanelEvent, + EMPTY_PANEL, + panelTakesFocusKey, + panelView, + reducePanel, +} from "./state/panel.ts"; +import { toAskResult } from "./state/result.ts"; +import type { AskParams, AskResult, AskState } from "./types.ts"; +import { type AskPanel, createAskPanel } from "./ui/panel.ts"; + +export const ASK_PENDING_WIDGET_KEY = "pi-ask:pending"; + +export interface AskBackgroundDeps { + /** Runs `task` after the current lifecycle dispatch has finished. */ + defer?: (task: () => void) => void; +} + +export interface AskBackground { + /** The session started, or the tree moved: rebuild from the branch. */ + attach(ctx: ExtensionContext): void; + /** `turn_end` / `agent_before_settle`: pending answers join the run. */ + boundary( + ctx: ExtensionContext, + event: AskBoundaryEvent + ): AskBoundaryResult | undefined; + /** Stop for good: the runtime this belongs to is going away. */ + dispose(): void; + /** + * `requestId` was journalled as a background or deferred form. Returns + * how many forms are now waiting. + */ + enqueue( + ctx: ExtensionContext, + requestId: string, + origin: "background" | "deferred" + ): number; + /** + * Runs a blocking form. It owns the keyboard: the panel is off screen + * until `run` settles, then returns with the focus it had. + */ + foreground(ctx: ExtensionContext, run: () => Promise): Promise; + /** Pi may have become idle without a run settling: deliver if so. */ + poke(ctx: ExtensionContext): void; + /** `/ask-panel`: show the panel and give it the keyboard. */ + reopen(ctx: ExtensionContext): void; + /** The agent run is over; `aborted` when the user stopped it. */ + settled(ctx: ExtensionContext, aborted?: boolean): void; +} + +export function registerAskBackground( + pi: ExtensionAPI, + runtime: AskRuntime, + deps: AskBackgroundDeps = {} +): AskBackground { + const background = createAskBackground(pi, runtime, deps); + runtime.background = background; + pi.on("session_start", (_event, ctx) => background.attach(ctx)); + pi.on("session_tree", (_event, ctx) => background.attach(ctx)); + pi.on("session_shutdown", () => background.dispose()); + pi.on("turn_end", (event, ctx) => background.boundary(ctx, event) as never); + pi.on( + "agent_before_settle", + (event, ctx) => background.boundary(ctx, event) as never + ); + pi.on("agent_settled", (event, ctx) => + background.settled(ctx, event.aborted) + ); + // A manual compaction keeps Pi busy without a run; pick up afterwards. + pi.on("session_compact", (_event, ctx) => background.poke(ctx)); + pi.registerMessageRenderer?.( + ASK_ANSWER_MESSAGE_TYPE, + renderAskAnswerMessage as never + ); + pi.registerCommand?.("ask-panel", { + description: "Show waiting ask_user questions", + handler: async (_args: string, ctx: ExtensionCommandContext) => { + background.reopen(ctx); + }, + }); + return background; +} + +export function createAskBackground( + pi: Pick, + { journal, live }: AskRuntime, + deps: AskBackgroundDeps = {} +): AskBackground { + const defer = deps.defer ?? ((task) => setTimeout(task, 0)); + const delivery = createAskDelivery(pi); + const recorders = new Map void>(); + // Recovered forms announced in this process. + const announced = new Set(); + let state = EMPTY_PANEL; + let records = new Map(); + let ctx: ExtensionContext | undefined; + let config: AskConfig = DEFAULT_ASK_CONFIG; + let configLoaded = false; + let disposed = false; + let indicator: string | undefined; + let focusWarned = false; + let unbindInput: (() => void) | undefined; + let boundUi: ExtensionContext["ui"] | undefined; + const unsubscribeConfig = getAskConfigStore().subscribe((next) => { + config = next; + indicator = undefined; + render(); + }); + + const panel: AskPanel = createAskPanel({ + // The host moved focus itself: follow it, without touching the screen. + onBlur() { + state = reducePanel(state, { type: "blurred" }); + updateIndicator(); + }, + onFocus() { + state = reducePanel(state, { type: "refocused" }); + updateIndicator(); + }, + onHide(requestId) { + if (!isQueued(requestId)) { + return; + } + journal.recordPanel(true, requestId); + dispatch({ type: "hide" }); + }, + onDone: complete, + onStateChange(requestId, formState) { + if (!isQueued(requestId)) { + return; + } + recorderFor(requestId)(formState); + updateIndicator(); + }, + }); + + /** On the active branch and waiting, as of the last rebuild. */ + function isQueued(requestId: string): boolean { + return !disposed && state.queue.includes(requestId); + } + + function recorderFor(requestId: string) { + let recorder = recorders.get(requestId); + if (!recorder) { + recorder = journal.draftRecorder(requestId, records.get(requestId)?.draft); + recorders.set(requestId, recorder); + } + return recorder; + } + + function readQueue(current: ExtensionContext) { + const journalState = readAskJournal(current); + const pending = pendingForms(journalState, live); + records = new Map(pending.map((record) => [record.requestId, record])); + for (const requestId of recorders.keys()) { + if (!records.has(requestId)) { + recorders.delete(requestId); + } + } + return { + queue: pending.map((record) => record.requestId), + hidden: journalState.panelHidden, + }; + } + + function dispatch(event: AskPanelEvent) { + state = reducePanel(state, event); + render(); + } + + /** Re-read the branch, then apply `toEvent` to the fresh queue. */ + function refresh( + toEvent: (queue: string[], hidden: boolean) => AskPanelEvent + ) { + if (disposed || !ctx) { + return; + } + try { + const { queue, hidden } = readQueue(ctx); + dispatch(toEvent(queue, hidden)); + } catch { + // A stale context: the next lifecycle event rebuilds. + } + } + + function render() { + if (disposed || !ctx) { + return; + } + try { + panel.retain(state.queue); + const focusedOk = panel.apply(ctx, panelView(state), loadForm); + if (!focusedOk) { + state = reducePanel(state, { type: "blurred" }); + if (!focusWarned) { + focusWarned = true; + ctx.ui.notify(askStrings().panelFocusUnsupported, "warning"); + } + } + updateIndicator(); + } catch { + // The UI is gone or not ready; the journal still has everything. + } + } + + function loadForm(requestId: string) { + const record = records.get(requestId); + if (!(record && ctx)) { + return; + } + if ( + record.mode === "foreground" && + !record.deferred && + !announced.has(requestId) + ) { + announced.add(requestId); + ctx.ui.notify(askStrings().recoveredNotice, "info"); + } + return { + requestId, + config, + draft: record.draft, + params: formToParams(record.form), + }; + } + + function updateIndicator() { + if (disposed || !ctx) { + return; + } + const forms = state.queue.length; + const text = + forms === 0 + ? undefined + : askStrings().pendingIndicator({ + forms, + questions: state.queue.reduce( + (sum, requestId) => sum + unansweredCount(requestId), + 0 + ), + key: getGlobalBindings(config).panelFocus.label, + focused: panelView(state).focused, + }); + if (text === indicator) { + return; + } + indicator = text; + ctx.ui.setWidget( + ASK_PENDING_WIDGET_KEY, + text === undefined ? undefined : [ctx.ui.theme.fg("dim", text)], + { placement: "belowEditor" } + ); + } + + function unansweredCount(requestId: string): number { + const record = records.get(requestId); + if (!record) { + return 0; + } + const formState = + panel.state(requestId) ?? + applyDraftSnapshot( + createInitialState(formToParams(record.form)), + record.draft + ); + return toAskResult(formState).unanswered.length; + } + + /** The panel's form was submitted or cancelled. */ + function complete(requestId: string, result: AskResult) { + const current = ctx; + if (disposed || !current) { + return; + } + try { + // The journal, not memory, says whether this branch still waits for + // this form: a form from another branch writes nothing here. + const record = getRecord(readAskJournal(current), requestId); + if ( + record && + isOpen(record) && + isQueued(requestId) && + result.status !== "unavailable" + ) { + journal.recordOutcome(requestId, result, "message"); + delivery.post(); + delivery.pump(current); + } + } catch { + // A stale context: nothing is written. + } + refresh((queue) => ({ type: "removed", queue })); + } + + function bindInput(current: ExtensionContext) { + if (boundUi === current.ui) { + return; + } + unbindInput?.(); + boundUi = current.ui; + unbindInput = current.ui.onTerminalInput?.((data) => { + if ( + disposed || + isKeyRelease(data) || + !panelTakesFocusKey(state) || + !matchesBinding(data, getGlobalBindings(config).panelFocus) + ) { + return; + } + toggleFocus(); + return { consume: true }; + }); + } + + function toggleFocus() { + if (state.hidden) { + journal.recordPanel(false, state.queue[0]); + } + dispatch({ type: "toggleFocus" }); + } + + function loadConfig() { + if (configLoaded) { + return; + } + configLoaded = true; + getAskConfigStore() + .ensureLoaded() + .then(({ config: loaded }) => { + config = loaded; + indicator = undefined; + render(); + }) + .catch(() => { + // Defaults stay in effect. + }); + } + + function poke(next: ExtensionContext) { + // Starting a turn from inside a lifecycle dispatch is too early. + defer(() => { + if (disposed) { + return; + } + try { + delivery.pump(next); + } catch { + // A stale context: the next event tries again. + } + }); + } + + function adopt(next: ExtensionContext): boolean { + if (disposed || next.mode !== "tui") { + return false; + } + ctx = next; + bindInput(next); + loadConfig(); + return true; + } + + return { + attach(next) { + if (!adopt(next)) { + return; + } + refresh((queue, hidden) => ({ type: "sync", queue, hidden })); + delivery.post(); + poke(next); + }, + poke, + enqueue(next, requestId, origin) { + if (!adopt(next)) { + return 0; + } + if (origin === "deferred") { + // "Later" means the keyboard goes back to the input. + state = reducePanel(state, { type: "blurred" }); + } + const focus = origin === "background" && editorIsEmpty(next); + refresh((queue) => ({ type: "arrived", queue, focus })); + if (state.hidden && origin === "background") { + next.ui.notify(askStrings().queuedHiddenNotice, "info"); + } + return state.queue.includes(requestId) ? state.queue.length : 0; + }, + async foreground(next, run) { + const adopted = adopt(next); + if (adopted) { + dispatch({ type: "foregroundOpened" }); + } + try { + return await run(); + } finally { + if (adopted) { + state = reducePanel(state, { type: "foregroundClosed" }); + refresh((queue) => ({ type: "removed", queue })); + } + } + }, + reopen(next) { + if (!adopt(next)) { + next.ui.notify(askStrings().panelNeedsTui, "error"); + return; + } + refresh((queue) => ({ type: "removed", queue })); + if (state.queue.length === 0) { + next.ui.notify(askStrings().nothingPending, "info"); + return; + } + if (state.hidden) { + journal.recordPanel(false, state.queue[0]); + } + dispatch({ type: "reopen" }); + }, + boundary(next, event) { + if (disposed) { + return; + } + try { + return delivery.boundary(next, event); + } catch { + return; + } + }, + settled(next, aborted) { + if (disposed) { + return; + } + try { + delivery.pump(next, { trigger: "settled", aborted }); + } catch { + // A stale context: the next event tries again. + } + }, + dispose() { + if (disposed) { + return; + } + try { + panel.discard(); + ctx?.ui.setWidget(ASK_PENDING_WIDGET_KEY, undefined); + } catch { + // The UI is already gone. + } + disposed = true; + ctx = undefined; + unbindInput?.(); + unsubscribeConfig(); + }, + }; +} + +/** A new form may take the keyboard only if no message is being written. */ +function editorIsEmpty(ctx: ExtensionContext): boolean { + try { + return ctx.ui.getEditorText().trim().length === 0; + } catch { + return false; + } +} + +export function formToParams(form: AskFormSnapshot): AskParams { + return { + title: form.title, + questions: form.questions, + ...(form.timeoutSeconds === undefined + ? {} + : { timeoutSeconds: form.timeoutSeconds }), + }; +} diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 1e5f371e..9482e519 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -1,72 +1,250 @@ /** - * Sends a journalled outcome to the agent as a follow-up message. Used when - * the tool call that asked is no longer waiting (recovered, deferred or - * background forms). Exactly-once is the journal's job: callers pass only - * records from `undeliveredOutcomes`, and the marker is written here. + * Sends journalled outcomes to the agent as a follow-up message. Used when + * the tool call that asked is no longer waiting: background, deferred and + * recovered forms. + * + * Exactly-once rests on the session branch. An outcome is delivered when its + * `pi-ask:answer` message is on the branch; until then it is pending. The + * only in-memory state is the set of outcomes sent and not yet seen there, + * which keeps a message that is still on its way from being sent again. + * How a pending outcome is sent is decided in `state/outbox.ts`. */ import type { ExtensionAPI, ExtensionContext, } from "@earendil-works/pi-coding-agent"; +import { Text } from "@earendil-works/pi-tui"; import { askStrings } from "./i18n.ts"; import { ASK_ANSWER_MESSAGE_TYPE, type AskAnswerMessageDetails, type AskOutcomeEntry, } from "./journal/entries.ts"; -import type { AskJournal } from "./journal/journal.ts"; -import { summarizeResult } from "./state/result.ts"; -import type { AskResult } from "./types.ts"; +import { readAskJournal } from "./journal/journal.ts"; +import { undeliveredOutcomes } from "./journal/replay.ts"; +import { renderResultText } from "./result.ts"; +import { + type AskDeliverySituation, + type AskDeliveryStep, + boundaryContinues, + planDelivery, +} from "./state/outbox.ts"; +import type { AskResult, AskResultAnswer } from "./types.ts"; + +type DeliveryContext = Pick; + +/** The part of a `turn_end` / `agent_before_settle` event that is read. */ +export interface AskBoundaryEvent { + entries?: readonly unknown[]; + message?: unknown; +} -type SendOptions = Parameters[1]; +/** What Pi appends at the boundary; shaped as its `custom_message` draft. */ +export interface AskBoundaryResult { + continue?: boolean; + entries: unknown[]; +} + +export interface AskDelivery { + /** + * A turn boundary of a working agent. Returns the pending outcomes as + * entries for Pi to append there, or undefined when there are none. + */ + boundary( + ctx: DeliveryContext, + event: AskBoundaryEvent + ): AskBoundaryResult | undefined; + /** An outcome was just journalled with channel `message`. */ + post(): void; + /** Deliver what can be delivered now. `settled`: the run is over. */ + pump( + ctx: DeliveryContext, + situation?: Partial> + ): void; +} /** Model-facing text of the follow-up message. */ export function formatDeliveredOutcome(result: AskResult): string { const requestId = result.requestId ?? ""; - if (result.status === "cancelled") { - return askStrings().cancelDelivered(requestId, result.title); - } - return [ - askStrings().answerDelivered(requestId, result.title), - summarizeResult(result), - ].join("\n"); + const cancelled = result.status === "cancelled"; + const heading = cancelled + ? askStrings().cancelDelivered(requestId, result.title) + : askStrings().answerDelivered(requestId, result.title); + // Each question is named by id and prompt: the call that asked may be + // far back in the context, or compacted away. + const lines = result.questions.map((question) => { + const asked = `- ${question.id} "${oneLine(question.prompt)}"`; + return cancelled + ? asked + : `${asked}: ${formatAnswer(result.answers[question.id])}`; + }); + return [heading, ...lines].join("\n"); } -/** - * An answer wakes an idle agent and joins a working one at the next turn - * boundary. A cancellation is added as context but never starts a turn. - */ -export function deliveryOptions( - result: AskResult, - idle: boolean -): SendOptions { - if (result.status === "cancelled") { - return { triggerTurn: false }; +function formatAnswer(answer: AskResultAnswer | undefined): string { + if (!answer) { + return "(no answer)"; + } + const parts = answer.values.map((value, index) => { + const label = answer.labels[index] ?? value; + const note = answer.optionNotes?.[value]; + return `${label} [${value}]${note ? ` (note: ${oneLine(note)})` : ""}`; + }); + const custom = answer.customText?.trim(); + if (custom) { + parts.push(`wrote "${oneLine(custom)}"`); + } + if (answer.note) { + parts.push(`note: ${oneLine(answer.note)}`); } - return idle ? { triggerTurn: true } : { triggerTurn: true, deliverAs: "steer" }; + return parts.join("; ") || "(no answer)"; } -export function deliverAskOutcome( - pi: Pick, - ctx: Pick, - journal: AskJournal, - outcome: AskOutcomeEntry -): void { +function oneLine(text: string): string { + return text.replace(/\s+/g, " ").trim(); +} + +function answerMessage(outcome: AskOutcomeEntry) { const details: AskAnswerMessageDetails = { requestId: outcome.requestId, outcomeId: outcome.outcomeId, result: outcome.result, }; - // Send first: if it throws, no marker is written and it is retried on - // the next replay. The persisted message also proves delivery by itself. - pi.sendMessage( - { - customType: ASK_ANSWER_MESSAGE_TYPE, - content: formatDeliveredOutcome(outcome.result), - display: true, - details, + return { + customType: ASK_ANSWER_MESSAGE_TYPE, + content: formatDeliveredOutcome(outcome.result), + display: true, + details, + }; +} + +export function createAskDelivery( + pi: Pick +): AskDelivery { + // Sent in this process, not yet on the branch. Never cleared on a timer or + // a lifecycle event: a second send is the one thing that must not happen. + const inFlight = new Set(); + // False while the branch is known to have nothing pending, so that turn + // boundaries of an ordinary run cost nothing. + let watching = true; + + function plan(ctx: DeliveryContext, situation: AskDeliverySituation) { + if (!watching) { + return; + } + const pending = undeliveredOutcomes(readAskJournal(ctx)); + if (pending.length === 0) { + watching = false; + return; + } + const outcomes = new Map( + pending.map(({ outcome }) => [outcome.outcomeId, outcome]) + ); + const steps = planDelivery( + pending.map(({ outcome }) => ({ + outcomeId: outcome.outcomeId, + cancelled: outcome.result.status === "cancelled", + inFlight: inFlight.has(outcome.outcomeId), + })), + situation + ); + return { outcomes, steps }; + } + + function send(outcome: AskOutcomeEntry, step: AskDeliveryStep) { + inFlight.add(outcome.outcomeId); + try { + pi.sendMessage(answerMessage(outcome), { + triggerTurn: step.action === "wake", + }); + } catch { + // Not sent: leave it pending for the next attempt. + inFlight.delete(outcome.outcomeId); + } + } + + return { + post() { + watching = true; + }, + pump(ctx, situation = {}) { + const planned = plan(ctx, { + trigger: situation.trigger ?? "now", + aborted: situation.aborted, + idle: ctx.isIdle(), + }); + for (const step of planned?.steps ?? []) { + const outcome = planned?.outcomes.get(step.outcomeId); + if (outcome && (step.action === "wake" || step.action === "append")) { + send(outcome, step); + } + } + }, + boundary(ctx, event) { + const planned = plan(ctx, { trigger: "boundary", idle: false }); + const proposed = (planned?.steps ?? []) + .filter((step) => step.action === "propose") + .map((step) => planned?.outcomes.get(step.outcomeId)) + .filter((outcome): outcome is AskOutcomeEntry => !!outcome); + if (proposed.length === 0) { + return; + } + // Not marked in flight: Pi appends these as soon as the handlers + // return, so the branch itself answers the next check. + const entries = [ + ...(event.entries ?? []), + ...proposed.map((outcome) => ({ + type: "custom_message", + ...answerMessage(outcome), + })), + ]; + const wantsTurn = boundaryContinues( + proposed.map((outcome) => ({ + cancelled: outcome.result.status === "cancelled", + })), + stopReason(event.message) + ); + return wantsTurn ? { entries, continue: true } : { entries }; }, - deliveryOptions(outcome.result, ctx.isIdle()) + }; +} + +function stopReason(message: unknown): string | undefined { + const reason = (message as { stopReason?: unknown } | undefined)?.stopReason; + return typeof reason === "string" ? reason : undefined; +} + +type MessageTheme = ExtensionContext["ui"]["theme"]; + +/** Transcript card for a delivered answer, in place of the raw message. */ +export function renderAskAnswerMessage( + message: { details?: unknown }, + _options: unknown, + theme: MessageTheme +) { + const details = message.details as + | Partial + | undefined; + const result = details?.result; + if (!(result && Array.isArray(result.questions))) { + return; + } + const strings = askStrings(); + const label = + result.status === "cancelled" + ? strings.cancelledCardLabel + : strings.answeredCardLabel; + const subject = result.title ?? result.requestId ?? details?.requestId ?? ""; + const heading = + theme.fg("toolTitle", theme.bold("ask_user ")) + + theme.fg("muted", [label, subject].filter(Boolean).join(" · ")); + const body = renderResultText(result); + return new Text( + [ + heading, + result.status === "submitted" ? body : theme.fg("warning", body), + ].join("\n"), + 1, + 0 ); - journal.recordDelivered(outcome.requestId, outcome.outcomeId); } diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index e2d66a51..12198941 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -30,7 +30,7 @@ export interface AskStrings { /** One-line summary returned to the model when the user submits. */ submittedSummary: string; /** Receipt returned to the model for a background call. */ - queuedSummary: (requestId: string) => string; + queuedSummary: (requestId: string, pending?: number) => string; /** Receipt returned to the model when the user chose "answer later". */ deferredSummary: (requestId: string) => string; /** Trailer returned to the model after the time limit lapsed. */ @@ -41,6 +41,24 @@ export interface AskStrings { cancelDelivered: (requestId: string, title?: string) => string; /** Shown to the user when an interrupted form reopens. */ recoveredNotice: string; + /** Line under the editor while forms wait in the queue. */ + pendingIndicator: (info: { + focused: boolean; + forms: number; + key: string; + questions: number; + }) => string; + /** A background question arrived while the panel is hidden. */ + queuedHiddenNotice: string; + /** `/ask-panel` with nothing in the queue. */ + nothingPending: string; + /** `/ask-panel` outside the interactive TUI. */ + panelNeedsTui: string; + /** This Pi cannot move the keyboard into the panel. */ + panelFocusUnsupported: string; + /** Transcript card headings for a delivered answer or cancellation. */ + answeredCardLabel: string; + cancelledCardLabel: string; /** Short transcript labels for the non-answer statuses. */ queuedLabel: string; deferredLabel: string; @@ -52,6 +70,10 @@ const EN_RECEIPT_RULES = const ZH_RECEIPT_RULES = "这只是回执,不是回答,也不是批准。只继续不依赖该回答的工作;回答会在之后的消息中送达。不要重复提问。"; +function count(value: number, noun: string): string { + return `${value} ${noun}${value === 1 ? "" : "s"}`; +} + function formRef(requestId: string, title?: string): string { return title ? `${requestId} (${title})` : requestId; } @@ -69,8 +91,10 @@ const EN_STRINGS: AskStrings = { recommendedMarker: "(Recommended)", cancelledSummary: "User cancelled the ask flow", submittedSummary: "User submitted the ask flow", - queuedSummary: (requestId) => - `Queued as ${requestId}. ${EN_RECEIPT_RULES}`, + queuedSummary: (requestId, pending) => + `Queued as ${requestId}${ + pending && pending > 1 ? ` (${pending} forms waiting)` : "" + }. ${EN_RECEIPT_RULES}`, deferredSummary: (requestId) => `User will answer later (${requestId}). ${EN_RECEIPT_RULES}`, expiredSummary: (fallbackLabels) => @@ -86,6 +110,23 @@ const EN_STRINGS: AskStrings = { cancelDelivered: (requestId, title) => `User cancelled your earlier ask_user form ${formRef(requestId, title)}. Cancellation is not approval; keep risky actions blocked.`, recoveredNotice: "Reopened a question left unanswered when Pi last stopped", + pendingIndicator: ({ focused, forms, key, questions }) => + [ + questions > 0 + ? `? ${count(questions, "unanswered question")} in ${count(forms, "form")}` + : `? ${count(forms, "form")} ready to submit`, + key ? `${key} ${focused ? "back to input" : "answer"}` : "", + "/ask-panel", + ] + .filter(Boolean) + .join(" · "), + queuedHiddenNotice: "New question queued. /ask-panel to open it", + nothingPending: "No questions are waiting", + panelNeedsTui: "/ask-panel requires interactive TUI mode.", + panelFocusUnsupported: + "This Pi version cannot focus the question panel; update Pi to answer queued questions", + answeredCardLabel: "answered", + cancelledCardLabel: "cancelled", queuedLabel: "Queued", deferredLabel: "Answer later", expiredLabel: "Expired", @@ -104,7 +145,10 @@ const ZH_STRINGS: AskStrings = { recommendedMarker: "(推荐)", cancelledSummary: "用户取消了提问流程", submittedSummary: "用户提交了提问流程", - queuedSummary: (requestId) => `已排队,编号 ${requestId}。${ZH_RECEIPT_RULES}`, + queuedSummary: (requestId, pending) => + `已排队,编号 ${requestId}${ + pending && pending > 1 ? `(共 ${pending} 个表单待回答)` : "" + }。${ZH_RECEIPT_RULES}`, deferredSummary: (requestId) => `用户稍后回答(${requestId})。${ZH_RECEIPT_RULES}`, expiredSummary: (fallbackLabels) => @@ -120,6 +164,22 @@ const ZH_STRINGS: AskStrings = { cancelDelivered: (requestId, title) => `用户取消了你之前的 ask_user 表单 ${formRef(requestId, title)}。取消不代表批准;有风险的操作仍须保持阻止。`, recoveredNotice: "已重新打开上次 Pi 停止时未回答的问题", + pendingIndicator: ({ focused, forms, key, questions }) => + [ + questions > 0 + ? `? ${forms} 个表单中有 ${questions} 个问题待回答` + : `? ${forms} 个表单可以提交`, + key ? `${key} ${focused ? "返回输入框" : "回答"}` : "", + "/ask-panel", + ] + .filter(Boolean) + .join(" · "), + queuedHiddenNotice: "有新问题已排队。输入 /ask-panel 打开", + nothingPending: "没有待回答的问题", + panelNeedsTui: "/ask-panel 需要交互式 TUI 模式。", + panelFocusUnsupported: "当前 Pi 版本无法聚焦问题面板;请更新 Pi 以回答排队的问题", + answeredCardLabel: "已回答", + cancelledCardLabel: "已取消", queuedLabel: "已排队", deferredLabel: "稍后回答", expiredLabel: "已超时", diff --git a/pi-ask/src/index.ts b/pi-ask/src/index.ts index 4897632a..c8bd964a 100644 --- a/pi-ask/src/index.ts +++ b/pi-ask/src/index.ts @@ -2,9 +2,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { registerAnswerCommands } from "./answer-commands.ts"; import { registerAskSettingsCommand } from "./ask-settings-command.ts"; import { registerAskTool } from "./ask-tool.ts"; +import { registerAskBackground } from "./background.ts"; import { getAskConfigStore, resetAskConfigStore } from "./config/store.ts"; import { resolveAskFeatures } from "./features.ts"; -import { registerAskRecovery } from "./recovery.ts"; import { createAskRuntime } from "./runtime.ts"; export default async function askExtension(pi: ExtensionAPI) { @@ -13,8 +13,8 @@ export default async function askExtension(pi: ExtensionAPI) { // and never invalidates the prompt cache mid-session. const features = resolveAskFeatures(await getAskConfigStore().peek()); const runtime = createAskRuntime(pi); + registerAskBackground(pi, runtime); registerAskTool(pi, { features, runtime }); - registerAskRecovery(pi, runtime); registerAskSettingsCommand(pi); registerAnswerCommands(pi); } diff --git a/pi-ask/src/recovery.ts b/pi-ask/src/recovery.ts deleted file mode 100644 index 1c8d518e..00000000 --- a/pi-ask/src/recovery.ts +++ /dev/null @@ -1,195 +0,0 @@ -/** - * Interrupted-form recovery. A foreground form that was open when Pi quit or - * crashed has a form entry and no outcome on the active branch. In TUI mode - * it is reopened with its draft; the original tool call's promise is gone, - * so the result goes to the agent as a follow-up message. - */ -import type { - ExtensionAPI, - ExtensionContext, -} from "@earendil-works/pi-coding-agent"; -import { deliverAskOutcome } from "./delivery.ts"; -import { askStrings } from "./i18n.ts"; -import type { AskFormSnapshot } from "./journal/entries.ts"; -import { readAskJournal } from "./journal/journal.ts"; -import { - getRecord, - interruptedForms, - isOpen, - undeliveredOutcomes, -} from "./journal/replay.ts"; -import type { AskRuntime } from "./runtime.ts"; -import type { AskParams } from "./types.ts"; -import { runAskFlow } from "./ui/controller.ts"; - -export interface AskRecoveryDeps { - /** Runs `task` after the current lifecycle dispatch has finished. */ - defer?: (task: () => void) => void; - runFlow?: typeof runAskFlow; -} - -export interface AskRecovery { - /** Stop for good: the session this runtime belongs to is going away. */ - dispose(): void; - /** Check the active branch; returns at once, never waits for a form. */ - schedule(ctx: ExtensionContext): void; - /** Resolves when no recovery work is in flight. For tests. */ - settled(): Promise; -} - -export function registerAskRecovery( - pi: ExtensionAPI, - runtime: AskRuntime, - deps: AskRecoveryDeps = {} -): AskRecovery { - const recovery = createAskRecovery(pi, runtime, deps); - // Handlers only schedule: an open form must not hold up Pi's lifecycle. - pi.on("session_start", (_event, ctx) => recovery.schedule(ctx)); - pi.on("session_tree", (_event, ctx) => recovery.schedule(ctx)); - pi.on("session_shutdown", () => recovery.dispose()); - return recovery; -} - -export function createAskRecovery( - pi: Pick, - { journal, live }: AskRuntime, - deps: AskRecoveryDeps = {} -): AskRecovery { - const defer = deps.defer ?? ((task) => setTimeout(task, 0)); - const runFlow = deps.runFlow ?? runAskFlow; - // Guards for one process, on top of the journal: a form is offered once, - // and an outcome is sent once, even if a journal write was lost. - const offered = new Set(); - const sent = new Set(); - // The recovered form on screen. `detached` once its branch is no longer - // the active one: from then on nothing about it is written. - let open: { detached: boolean; requestId: string } | undefined; - let ctx: ExtensionContext | undefined; - let disposed = false; - let work: Promise | undefined; - let again = false; - - function deliverPending(current: ExtensionContext) { - for (const { outcome } of undeliveredOutcomes(readAskJournal(current))) { - if (sent.has(outcome.outcomeId)) { - continue; - } - sent.add(outcome.outcomeId); - deliverAskOutcome(pi, current, journal, outcome); - } - } - - async function recoverNext(current: ExtensionContext): Promise { - const record = interruptedForms(readAskJournal(current)).find( - ({ requestId }) => !(offered.has(requestId) || live.has(requestId)) - ); - if (!record) { - return false; - } - const { requestId } = record; - offered.add(requestId); - live.add(requestId); - const form = { requestId, detached: false }; - const recordDraft = journal.draftRecorder(requestId, record.draft); - let result: Awaited>; - open = form; - try { - current.ui.notify(askStrings().recoveredNotice, "info"); - result = await runFlow(current, formToParams(record.form), { - draft: record.draft, - onStateChange(state) { - if (!(disposed || form.detached)) { - recordDraft(state); - } - }, - }); - } finally { - open = undefined; - live.delete(requestId); - } - if (disposed) { - return false; - } - // The branch may have changed while the form was open. An answer is - // only written to a branch that still has the form and no outcome. - const latest = getRecord(readAskJournal(ctx ?? current), requestId); - if ( - form.detached || - !(latest && isOpen(latest)) || - result.status === "unavailable" - ) { - return true; - } - const outcome = journal.recordOutcome(requestId, result, "message"); - sent.add(outcome.outcomeId); - deliverAskOutcome(pi, ctx ?? current, journal, outcome); - return true; - } - - async function run() { - do { - again = false; - const current = ctx; - if (disposed || !current) { - return; - } - try { - deliverPending(current); - while (await recoverNext(current)) { - // One form at a time, in request order. - } - } catch { - // A stale context or a UI that failed to open: give up quietly. - // Unanswered forms stay in the journal for the next start. - } - } while (again); - } - - return { - schedule(next) { - if (disposed || next.mode !== "tui") { - return; - } - ctx = next; - if (open && !isOnBranch(next, open.requestId)) { - open.detached = true; - } - if (work) { - again = true; - return; - } - work = new Promise((resolve) => defer(resolve)) - .then(run) - .finally(() => { - work = undefined; - }); - }, - dispose() { - disposed = true; - ctx = undefined; - }, - async settled() { - while (work) { - await work; - } - }, - }; -} - -function isOnBranch(ctx: ExtensionContext, requestId: string): boolean { - try { - return !!getRecord(readAskJournal(ctx), requestId); - } catch { - return false; - } -} - -function formToParams(form: AskFormSnapshot): AskParams { - return { - title: form.title, - questions: form.questions, - ...(form.timeoutSeconds === undefined - ? {} - : { timeoutSeconds: form.timeoutSeconds }), - }; -} diff --git a/pi-ask/src/runtime.ts b/pi-ask/src/runtime.ts index 89b1a3ff..d3042ff5 100644 --- a/pi-ask/src/runtime.ts +++ b/pi-ask/src/runtime.ts @@ -1,12 +1,18 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import type { AskBackground } from "./background.ts"; import { type AskJournal, createSessionAskJournal } from "./journal/journal.ts"; /** State shared by the tool and the lifecycle handlers of one extension load. */ export interface AskRuntime { + /** + * Queue, panel and delivery for forms no tool call waits for. Absent when + * only the tool is registered: every call then blocks. + */ + background?: AskBackground; journal: AskJournal; /** - * Request ids whose form is on screen in this process. Recovery skips - * them: an open form is not an interrupted one. + * Request ids whose blocking form is on screen in this process. The queue + * skips them: an open form is not an interrupted one. */ live: Set; } diff --git a/pi-ask/src/state/result.ts b/pi-ask/src/state/result.ts index 3d126ff0..4d0e9ccd 100644 --- a/pi-ask/src/state/result.ts +++ b/pi-ask/src/state/result.ts @@ -68,7 +68,7 @@ export function summarizeResult(result: AskResult): string { // Receipts carry their own rules so the guidance costs tokens only when // it applies, instead of living in the recurring prompt guidelines. if (result.status === "queued") { - return askStrings().queuedSummary(result.requestId ?? ""); + return askStrings().queuedSummary(result.requestId ?? "", result.pending); } if (result.status === "deferred") { return askStrings().deferredSummary(result.requestId ?? ""); diff --git a/pi-ask/src/types.ts b/pi-ask/src/types.ts index 8d5e97c2..435cccd9 100644 --- a/pi-ask/src/types.ts +++ b/pi-ask/src/types.ts @@ -93,6 +93,8 @@ export interface AskResult { /** Why the user cancelled, when they said. */ comment?: string; error?: AskValidationError; + /** Forms waiting for an answer, this one included (`queued` only). */ + pending?: number; /** Question ids whose answer is an auto-applied fallback (`expired` only). */ expired?: string[]; questions: AskQuestionSummary[]; diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 4c761c7b..df808dbe 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -69,19 +69,47 @@ type AskFlowParams = AskParams & }; export interface AskFlowOptions { + /** + * Offer "answer later" on a blocking form: the flow then resolves with a + * `deferred` result and the caller moves the form to the queue. + */ + allowDefer?: boolean; /** Answers to restore, e.g. from the journal of an interrupted form. */ draft?: AskDraftSnapshot; + /** Called for every key the form receives, before it is handled. */ + onInput?: (data: string) => void; /** Called after every state change while the form is open. */ onStateChange?: (state: AskState) => void; + /** + * Set when the form is drawn in the background panel. There the cancel + * and "answer later" keys only put the panel away (`onHide`); the form is + * cancelled with the dismiss key or from the review tab. + */ + panel?: { onHide: () => void }; +} + +/** The form as a TUI component, for hosts other than `ctx.ui.custom`. */ +export interface AskFlowComponent { + dispose(): void; + focused: boolean; + /** The live form state, including unsaved editor text. */ + getState(): AskState; + handleInput(data: string): void; + invalidate(): void; + render(width: number): string[]; } interface AskFlowController { + allowDefer: boolean; config: AskConfig; configNotice?: string; ctx: ExtensionContext; done: Done; editor: Editor; + focused: boolean; + onInput?: (data: string) => void; onStateChange?: (state: AskState) => void; + panel?: { onHide: () => void }; pendingDiscardConfirm: boolean; pendingQuestionTypeChangeQuestionId?: string; pendingReviewShortcutActionIndex?: number; @@ -116,22 +144,26 @@ export async function runAskFlow( ); } -function createAskFlowController( +export function createAskFlowController( [tui, theme, _keybindings, done]: [ Tui, Theme, - Keybindings, + Keybindings | undefined, (result: AskResult) => void, ], params: AskFlowParams -) { +): AskFlowComponent { const controller: AskFlowController = { + allowDefer: params.allowDefer === true, config: params.config, configNotice: params.configNotice, ctx: params.ctx, done, editor: createEditor(tui, theme, params.cwd), + focused: false, + onInput: params.onInput, onStateChange: params.onStateChange, + panel: params.panel, settingsOpen: false, state: applyDraftSnapshot(createInitialState(params), params.draft), suppressAutoInputForSelection: false, @@ -165,16 +197,22 @@ function createAskFlowController( return { get focused() { - return controller.editor.focused; + return controller.focused; }, set focused(value: boolean) { + controller.focused = value; controller.editor.focused = value; }, + getState: () => + isEditingView(controller.state) + ? saveEditorDraft(controller.state, controller.editor.getText()) + : controller.state, render: (width: number) => renderController(controller, width), invalidate() { controller.editor.invalidate(); }, handleInput(data: string) { + controller.onInput?.(data); handleControllerInput(controller, data); }, dispose() { @@ -193,6 +231,9 @@ function renderController( footerNotice: getFooterNotice(controller), reviewShortcutHint: getActiveReviewShortcutHint(controller), state: controller.state, + surface: controller.panel + ? { panel: { focused: controller.focused } } + : { defer: controller.allowDefer }, theme: controller.theme, width, }); @@ -232,6 +273,10 @@ function handleEditingCommand( handleExitFlow(controller, dismissFlow(controller.state)); return; } + if (command.kind === "later") { + answerLater(controller); + return; + } if (command.kind === "showSettings") { showSettingsModal(controller); return; @@ -296,8 +341,17 @@ function handleNavigationCommand( case "cancel": clearReviewShortcutPending(controller); clearQuestionTypeChangePending(controller); + if (controller.panel) { + // Hiding cancels nothing; the form waits in the queue. + answerLater(controller); + return; + } handleExitFlow(controller, cancelFlow(controller.state)); return; + case "later": + clearPendingConfirms(controller); + answerLater(controller); + return; case "numberShortcut": if (handleReviewShortcutNumber(controller, command.digit)) { return; @@ -427,6 +481,29 @@ function closeEditor(controller: AskFlowController) { refresh(controller); } +/** + * "Answer later". Typed text is saved into the draft first. In the panel + * the form stays open and only the panel goes away; a blocking form ends + * with a `deferred` receipt. + */ +function answerLater(controller: AskFlowController) { + if (!(controller.panel || controller.allowDefer)) { + return; + } + // The draft keeps typed text; the open editor itself is left as it is. + const saved = isEditingView(controller.state) + ? saveEditorDraft(controller.state, controller.editor.getText()) + : controller.state; + controller.pendingDiscardConfirm = false; + controller.onStateChange?.(saved); + if (controller.panel) { + controller.tui.requestRender(); + controller.panel.onHide(); + return; + } + controller.done(toAskResult(saved, "deferred")); +} + function handleExitFlow(controller: AskFlowController, nextState: AskState) { if (!shouldRequestDismissConfirmation(controller)) { commitState(controller, nextState, { finish: true }); diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts new file mode 100644 index 00000000..5aec1642 --- /dev/null +++ b/pi-ask/src/ui/panel.ts @@ -0,0 +1,260 @@ +/** + * The background panel: one question form drawn as a widget above Pi's + * editor. The editor stays where it is and keeps its text; the keyboard goes + * to whichever of the two has TUI focus. + * + * This file is only the Pi/TUI wiring. What is shown, and who owns the + * keyboard, is decided in `state/panel.ts` and applied through `apply`. + */ +import type { ExtensionContext } from "@earendil-works/pi-coding-agent"; +import type { AskConfig } from "../config/schema.ts"; +import type { AskDraftSnapshot } from "../journal/entries.ts"; +import type { AskPanelView } from "../state/panel.ts"; +import type { AskParams, AskResult, AskState } from "../types.ts"; +import { type AskFlowComponent, createAskFlowController } from "./controller.ts"; + +export const ASK_PANEL_WIDGET_KEY = "pi-ask:panel"; + +type Ui = ExtensionContext["ui"]; +type WidgetFactory = Extract< + Parameters[1], + (...args: never[]) => unknown +>; +type Tui = Parameters[0]; +type Theme = Parameters[1]; +type TuiComponent = Parameters[0]; + +/** `getFocusedComponent` is on the TUI class, not on its interface. */ +type FocusAwareTui = Tui & { getFocusedComponent?: () => TuiComponent }; + +export interface AskPanelForm { + config: AskConfig; + draft?: AskDraftSnapshot; + params: AskParams; + requestId: string; +} + +export interface AskPanelCallbacks { + /** Pi moved the keyboard away from the panel (a dialog, the editor). */ + onBlur(): void; + /** Pi gave the keyboard back to the panel (a dialog over it closed). */ + onFocus(): void; + /** The form was submitted or cancelled. */ + onDone(requestId: string, result: AskResult): void; + /** The user asked to put the panel away. */ + onHide(requestId: string): void; + /** A key reached the form. */ + onInput?(requestId: string, data: string): void; + onStateChange(requestId: string, state: AskState): void; +} + +export interface AskPanel { + /** + * Make the screen match `view`. `load` is called only when the form to + * show is not the one already loaded. Returns false if the keyboard could + * not be given to the panel on this host. + */ + apply( + ctx: ExtensionContext, + view: AskPanelView, + load: (requestId: string) => AskPanelForm | undefined + ): boolean; + /** Drop the loaded form without telling anyone; nothing more is called. */ + discard(): void; + /** Drop the loaded form unless it is one of `requestIds`. */ + retain(requestIds: readonly string[]): void; + /** The loaded form's live state, including unsaved editor text. */ + state(requestId: string): AskState | undefined; +} + +export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { + let form: { component: AskFlowComponent; requestId: string } | undefined; + let mounted: { tui: FocusAwareTui; ui: Ui } | undefined; + let returnFocus: TuiComponent = null; + // True while this module moves focus itself, so the TUI's own blur + // notification is not mistaken for the host taking the keyboard. + let moving = false; + let focused = false; + + const shell = { + get focused() { + return focused; + }, + set focused(value: boolean) { + const changed = focused !== value; + focused = value; + if (form) { + form.component.focused = value; + } + if (changed && !moving) { + if (value) { + callbacks.onFocus(); + } else { + callbacks.onBlur(); + } + } + }, + render: (width: number) => form?.component.render(width) ?? [], + handleInput(data: string) { + form?.component.handleInput(data); + }, + invalidate() { + form?.component.invalidate(); + }, + /** Pi removed the widget itself (reload, session switch). */ + dispose() { + if (mounted) { + mounted = undefined; + focused = false; + returnFocus = null; + } + }, + }; + + function move(action: () => void) { + moving = true; + try { + action(); + } finally { + moving = false; + } + } + + function releaseFocus() { + if (!(mounted && focused)) { + return; + } + const { tui } = mounted; + move(() => tui.setFocus(returnFocus)); + returnFocus = null; + } + + function takeFocus(): boolean { + if (!mounted) { + return false; + } + if (focused) { + return true; + } + const { tui } = mounted; + if (typeof tui.getFocusedComponent !== "function") { + // Without it the keyboard could not be handed back to the editor. + return false; + } + returnFocus = tui.getFocusedComponent(); + move(() => tui.setFocus(shell as TuiComponent)); + return focused; + } + + function unloadForm() { + const loaded = form; + form = undefined; + loaded?.component.dispose(); + } + + function unmount() { + if (!mounted) { + return; + } + releaseFocus(); + const { ui } = mounted; + mounted = undefined; + try { + ui.setWidget(ASK_PANEL_WIDGET_KEY, undefined); + } catch { + // A torn-down UI has already dropped the widget. + } + } + + function mount(ctx: ExtensionContext, next: AskPanelForm) { + const build = (tui: Tui, theme: Theme) => { + mounted = { tui, ui: ctx.ui }; + if (form?.requestId !== next.requestId) { + unloadForm(); + form = { + requestId: next.requestId, + component: createPanelForm(ctx, tui, theme, next, callbacks), + }; + form.component.focused = focused; + } + return shell; + }; + if (mounted && mounted.ui === ctx.ui) { + // Same widget, next form: keep the mount and the focus. + build(mounted.tui, ctx.ui.theme); + mounted.tui.requestRender(); + return; + } + unmount(); + unloadForm(); + ctx.ui.setWidget(ASK_PANEL_WIDGET_KEY, build as never, { + placement: "aboveEditor", + }); + } + + return { + apply(ctx, view, load) { + if (!(view.visible && view.formId)) { + unmount(); + return true; + } + if ( + !mounted || + mounted.ui !== ctx.ui || + form?.requestId !== view.formId + ) { + const next = load(view.formId); + if (!next) { + unmount(); + return true; + } + mount(ctx, next); + } + if (!view.focused) { + releaseFocus(); + mounted?.tui.requestRender(); + return true; + } + const taken = takeFocus(); + mounted?.tui.requestRender(); + return taken; + }, + discard() { + unmount(); + unloadForm(); + }, + retain(requestIds) { + if (form && !requestIds.includes(form.requestId)) { + unloadForm(); + } + }, + state(requestId) { + return form?.requestId === requestId + ? form.component.getState() + : undefined; + }, + }; +} + +function createPanelForm( + ctx: ExtensionContext, + tui: Tui, + theme: Theme, + form: AskPanelForm, + callbacks: AskPanelCallbacks +): AskFlowComponent { + const { requestId } = form; + return createAskFlowController( + [tui, theme, undefined, (result) => callbacks.onDone(requestId, result)], + { + ...form.params, + config: form.config, + ctx, + cwd: ctx.cwd, + draft: form.draft, + onInput: (data) => callbacks.onInput?.(requestId, data), + onStateChange: (state) => callbacks.onStateChange(requestId, state), + panel: { onHide: () => callbacks.onHide(requestId) }, + } + ); +} diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts new file mode 100644 index 00000000..f5bd6b35 --- /dev/null +++ b/pi-ask/tests/background.test.ts @@ -0,0 +1,751 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { registerAskBackground } from "../src/background.ts"; +import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; +import { createAskRuntime } from "../src/runtime.ts"; +import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; + +const question = (id: string, prompt: string, first: string, second: string) => ({ + id, + label: id.toUpperCase(), + prompt, + options: [ + { value: first.toLowerCase(), label: first }, + { value: second.toLowerCase(), label: second }, + ], +}); + +const PARAMS = { + title: "Storage", + questions: [ + question("db", "Which database?", "Postgres", "SQLite"), + question("cache", "Which cache?", "Redis", "None"), + ], +}; +const ONE = (id: string, title = id) => ({ + title, + questions: [question(id, `Pick ${id}?`, "Yes", "No")], +}); +/** Answer every question with its first option and submit. */ +const SUBMIT_TWO = [KEY.enter, KEY.enter, KEY.enter]; +const SUBMIT_ONE = [KEY.enter, KEY.enter]; + +/** One Pi process: the extension wired as `src/index.ts` wires it. */ +function boot( + session?: SessionManager, + options: { background?: boolean; mode?: string } = {} +) { + const host = fakePi(session, options); + const runtime = createAskRuntime(host.pi); + registerAskBackground(host.pi, runtime); + registerAskTool(host.pi, { + runtime, + features: { background: options.background ?? true, expiry: false }, + }); + let calls = 0; + const ask = (params: object = PARAMS) => + host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); + const askInBackground = (params: object = PARAMS) => + ask({ ...params, background: true }); + return { ...host, host, ask, askInBackground }; +} + +type Host = ReturnType; + +async function start(host: Host, reason = "resume") { + host.emit("session_start", { reason }); + await tick(); +} + +const kinds = (host: Host) => host.journal().map((entry) => entry.kind); +const ids = (host: Host) => + host + .journal() + .filter((entry) => entry.kind === "form") + .map((entry) => entry.requestId); + +/** A session whose foreground form was open, DB answered, when Pi died. */ +async function interruptedSession() { + const first = boot(); + first.ask().catch(() => {}); + await tick(); + first.forms[0]?.press(KEY.enter); + assert.deepEqual(kinds(first), ["form", "draft"]); + return first.session; +} + +/** A started process with one background form in the focused panel. */ +async function withBackgroundForm(params: object = PARAMS) { + const host = boot(); + await start(host, "startup"); + const receipt = await host.askInBackground(params); + return { host, receipt, requestId: receipt.details.requestId as string }; +} + +beforeEach(quietConfig); + +// --- The tool call --------------------------------------------------------- + +test("a blocking call journals the form before waiting and the outcome before returning", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + assert.deepEqual(kinds(host), ["form"]); + assert.equal(host.journal()[0].mode, "foreground"); + assert.equal(host.journal()[0].toolCallId, "call-1"); + + host.forms[0]?.press(...SUBMIT_TWO); + const response = await pending; + const outcome = host.journal().at(-1); + assert.equal(outcome.kind, "outcome"); + assert.equal(outcome.channel, "tool"); + assert.equal(response.details.status, "submitted"); + assert.deepEqual(outcome.result, response.details); + + // Nothing is left to show and nothing is sent. + await start(host, "reload"); + assert.equal(host.forms.length, 1); + assert.equal(host.panelText(), ""); + assert.deepEqual(host.sent, []); +}); + +test("a background call returns a queued receipt at once and writes no outcome", async () => { + const { host, receipt, requestId } = await withBackgroundForm(); + assert.equal(receipt.details.status, "queued"); + assert.match(requestId, /^ask-[0-9a-f]{8}$/); + assert.equal(receipt.details.pending, 1); + assert.deepEqual(receipt.details.answers, {}); + assert.deepEqual(receipt.details.unanswered, ["db", "cache"]); + const text = receipt.content[0].text; + assert.match(text, new RegExp(requestId)); + assert.match(text, /not an answer or approval/); + assert.match(text, /later message/); + assert.match(text, /Do not ask again/); + assert.deepEqual(kinds(host), ["form"]); + assert.equal(host.journal()[0].mode, "background"); + assert.equal(host.forms.length, 0, "no blocking form was opened"); + assert.deepEqual(host.sent, []); + + const second = await host.askInBackground(ONE("x")); + assert.equal(second.details.pending, 2); + assert.match(second.content[0].text, /2 forms waiting/); +}); + +test("with background switched off a stale call carrying the flag blocks", async () => { + const host = boot(undefined, { background: false }); + await start(host, "startup"); + const pending = host.askInBackground(); + await tick(); + assert.equal(host.forms.length, 1); + assert.equal(host.journal()[0].mode, "foreground"); + host.forms[0]?.press(...SUBMIT_TWO); + assert.equal((await pending).details.status, "submitted"); + assert.equal(host.panelText(), ""); +}); + +test("hosts without the TUI block on a background call or report unavailable", async () => { + const rpc = boot(undefined, { mode: "rpc" }); + await start(rpc, "startup"); + const cards: string[] = []; + const ctx = { + mode: "rpc", + hasUI: true, + ui: { + select: (title: string, options: string[]) => { + cards.push(title); + return Promise.resolve( + options.find((option) => option.includes("Submit")) ?? options[0] + ); + }, + }, + }; + const response = await rpc.tools[0].execute( + "call-1", + { ...ONE("x"), background: true }, + undefined, + () => {}, + ctx + ); + assert.equal(response.details.status, "submitted"); + assert.ok(cards.length >= 2, "the card flow ran to its review card"); + assert.deepEqual(kinds(rpc), ["form", "outcome"]); + assert.equal(rpc.journal()[0].mode, "foreground"); + assert.equal(rpc.widgets.size, 0); + + const json = boot(undefined, { mode: "json" }); + const unavailable = await json.tools[0].execute( + "call-1", + { ...PARAMS, background: true }, + undefined, + () => {}, + { mode: "json", hasUI: false } + ); + assert.equal(unavailable.details.status, "unavailable"); + assert.deepEqual(kinds(json), ["form", "outcome"]); +}); + +// --- The panel ------------------------------------------------------------- + +test("the panel sits above the editor, which keeps its text and its keyboard", async () => { + const host = boot(); + await start(host, "startup"); + host.type("d", "r", "a", "f", "t"); + await host.askInBackground(); + + assert.match(host.panelText(), /Which database\?/); + assert.equal(host.widgets.get("pi-ask:panel")?.placement, "aboveEditor"); + assert.ok(host.focusIs("editor"), "a message in progress keeps the keyboard"); + host.type("!", KEY.enter); + assert.equal(host.editor.text, `draft!${KEY.enter}`, "ordinary input still works"); + assert.deepEqual(kinds(host), ["form"], "typing did not touch the form"); + + // One key moves the keyboard into the panel and back. + host.type(KEY.focus); + assert.ok(host.focusIs("panel")); + host.type(KEY.enter); + assert.equal(host.journal().at(-1).kind, "draft"); + assert.equal(host.editor.text, `draft!${KEY.enter}`, "the draft message is intact"); + host.type(KEY.focus); + assert.ok(host.focusIs("editor")); + assert.match(host.panelText(), /answer here/); +}); + +test("a new form takes the keyboard when no message is being written", async () => { + const { host } = await withBackgroundForm(); + assert.ok(host.focusIs("panel")); + assert.match(host.panelText(), /hide/); + assert.match(host.panelText(), /cancel form/); +}); + +test("hiding cancels nothing, survives a reload, and only the user reopens", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(KEY.enter, KEY.escape); + assert.equal(host.panelText(), ""); + assert.ok(host.focusIs("editor")); + assert.deepEqual(kinds(host), ["form", "draft", "panel"]); + assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); + assert.match(host.indicator() ?? "", /\/ask-panel/); + + // A new request neither reopens the panel nor takes the keyboard. + const second = await host.askInBackground(ONE("x")); + assert.equal(second.details.pending, 2); + assert.equal(host.panelText(), ""); + assert.ok(host.focusIs("editor")); + assert.equal(host.notices.length, 1); + assert.match(host.indicator() ?? "", /2 unanswered questions in 2 forms/); + host.type("h", "i"); + assert.equal(host.editor.text, "hi"); + + // Still hidden for a later process on the same branch. + const later = boot(host.session); + await start(later); + assert.equal(later.panelText(), ""); + assert.ok(later.focusIs("editor")); + assert.match(later.indicator() ?? "", /2 unanswered questions in 2 forms/); + + await later.command("ask-panel"); + assert.ok(later.focusIs("panel")); + assert.match(later.panelText(), /Which cache\?/, "the draft came back"); + later.type(KEY.enter, KEY.enter); + await tick(); + assert.equal(later.sent[0]?.message.details.requestId, requestId); + assert.match(later.panelText(), /Pick x\?/, "the next form follows"); +}); + +test("the focus key reopens a hidden panel; with nothing waiting it is an ordinary key", async () => { + const host = boot(); + await start(host, "startup"); + host.type(KEY.focus); + assert.equal(host.editor.text, KEY.focus, "passed through to the editor"); + await host.command("ask-panel"); + assert.deepEqual(host.notices, ["No questions are waiting"]); + + host.editor.text = ""; + await host.askInBackground(); + host.type(KEY.later); + assert.equal(host.panelText(), "", "the later key hides the panel too"); + host.type(KEY.focus); + assert.ok(host.focusIs("panel")); + assert.deepEqual(kinds(host), ["form", "panel", "panel"]); + assert.equal(host.journal().at(-1).hidden, false); +}); + +test("the pending indicator counts unanswered questions and clears", async () => { + const { host } = await withBackgroundForm(); + assert.match(host.indicator() ?? "", /2 unanswered questions in 1 form/); + assert.equal(host.widgets.get("pi-ask:pending")?.placement, "belowEditor"); + host.type(KEY.enter); + assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); + host.type(KEY.enter); + assert.match(host.indicator() ?? "", /1 form ready to submit/); + host.type(KEY.enter); + await tick(); + assert.equal(host.indicator(), undefined); + assert.equal(host.widgets.size, 0); + assert.ok(host.focusIs("editor")); +}); + +test("forms are shown one at a time in request order, across defer and reopen", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(ONE("a")); + // B is asked second as a blocking form and deferred; C arrives after. + const blocking = host.ask(ONE("b")); + await tick(); + host.forms[0]?.press(KEY.down, KEY.later); + const deferred = await blocking; + assert.equal(deferred.details.status, "deferred"); + await host.askInBackground(ONE("c")); + const [a, b, c] = ids(host); + + assert.match(host.panelText(), /Pick a\?/); + assert.doesNotMatch(host.panelText(), /Pick [bc]\?/); + + // A later process rebuilds the same order from the branch. + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + const order: string[] = []; + for (const expected of ["a", "b", "c"]) { + assert.match(later.panelText(), new RegExp(`Pick ${expected}\\?`)); + later.type(...SUBMIT_ONE); + await tick(); + later.recordWake(); + order.push(later.answers().at(-1).details.requestId); + later.settle(); + } + assert.deepEqual(order, [a, b, c]); + assert.equal(later.panelText(), ""); +}); + +// --- Defer ----------------------------------------------------------------- + +test("answer later returns a deferred receipt and keeps the draft for the panel", async () => { + const host = boot(); + await start(host, "startup"); + const pending = host.ask(); + await tick(); + assert.match(host.forms[0]?.render() ?? "", /answer later/); + host.forms[0]?.press(KEY.enter, KEY.later); + const response = await pending; + + assert.equal(response.details.status, "deferred"); + assert.deepEqual(response.details.answers, {}, "a receipt carries no answers"); + assert.match(response.content[0].text, /not an answer or approval/); + assert.match(response.content[0].text, /Do not ask again/); + assert.deepEqual(kinds(host), ["form", "draft", "defer"]); + + // In the panel, unfocused: "later" means the keyboard goes to the input. + assert.match(host.panelText(), /Which cache\?/); + assert.ok(host.focusIs("editor")); + assert.equal(host.sent.length, 0); + + host.type(KEY.focus, KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: true }); + assert.equal(host.sent[0]?.message.details.requestId, response.details.requestId); + assert.deepEqual( + host.sent[0]?.message.details.result.answers.db.values, + ["postgres"] + ); +}); + +test("answer later is not offered where there is no queue to move to", async () => { + const host = fakePi(); + registerAskTool(host.pi); + const pending = host.tools[0].execute("c", PARAMS, undefined, () => {}, host.ctx); + await tick(); + assert.doesNotMatch(host.forms[0]?.render() ?? "", /answer later/); + host.forms[0]?.press(KEY.later, ...SUBMIT_TWO); + assert.equal((await pending).details.status, "submitted"); +}); + +// --- Ownership ------------------------------------------------------------- + +test("a blocking call takes the keyboard from an open background form and gives it back", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(KEY.enter); + assert.ok(host.focusIs("panel")); + + const blocking = host.ask(ONE("urgent")); + await tick(); + assert.equal(host.panelText(), "", "only one form is on screen"); + assert.ok(host.focusIs("form")); + // Every key reaches the blocking form: no listener or panel swallows it. + host.type(KEY.focus); + host.type(...SUBMIT_ONE); + const response = await blocking; + assert.equal(response.details.status, "submitted"); + assert.deepEqual(response.details.answers.urgent.values, ["yes"]); + + // The background form is back as it was, with the keyboard. + assert.match(host.panelText(), /Which cache\?/); + assert.ok(host.focusIs("panel")); + host.type(KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, requestId); +}); + +test("a blocking form open in this process is never queued as interrupted", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + host.emit("session_tree"); + await start(host, "reload"); + assert.equal(host.forms.length, 1); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + + host.forms[0]?.press(...SUBMIT_TWO); + assert.equal((await pending).details.status, "submitted"); + assert.deepEqual(host.sent, []); +}); + +// --- Delivery -------------------------------------------------------------- + +test("an idle agent is woken by the answer, which names the form and each question", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + + assert.equal(host.sent.length, 1); + const [{ message, options }] = host.sent; + assert.equal(message.customType, ASK_ANSWER_MESSAGE_TYPE); + assert.deepEqual(options, { triggerTurn: true }); + assert.equal( + message.content, + [ + `User answered your earlier ask_user form ${requestId} (Storage):`, + '- db "Which database?": Postgres [postgres]', + '- cache "Which cache?": Redis [redis]', + ].join("\n") + ); + assert.equal(message.details.result.status, "submitted"); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); + assert.equal(host.journal().at(-1).channel, "message"); +}); + +test("no duplicate when the woken run reaches its turn boundary before the message is recorded", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 0, "the run has not recorded it yet"); + assert.equal(host.isIdle(), false); + + host.emit("turn_start"); + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); + host.recordWake(); + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + host.settle(); + await tick(); + + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 1); +}); + +test("a working agent gets the answer at the next turn boundary, once, with no extra turn started", async () => { + const { host, requestId } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + await tick(); + assert.deepEqual(host.sent, [], "nothing is sent while the agent works"); + + const first = host.turnEnd(); + assert.equal(first.continue, true, "the answer must be seen even on a final turn"); + assert.equal(first.entries.length, 1); + assert.equal(first.entries[0].type, "custom_message"); + assert.equal(first.entries[0].customType, ASK_ANSWER_MESSAGE_TYPE); + assert.equal(first.entries[0].details.requestId, requestId); + assert.match(first.entries[0].content, /db "Which database\?": Postgres/); + + // Turn boundary, then settle: the same answer is not offered or sent again. + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); + host.settle(); + await tick(); + assert.deepEqual(host.sent, []); + assert.equal(host.answers().length, 1); +}); + +test("an answer given after the last turn joins at the settle boundary", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.turnEnd(); + host.type(...SUBMIT_TWO); + const boundary = host.beforeSettle(); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, true); + host.settle(); + await tick(); + assert.deepEqual(host.sent, []); + assert.equal(host.answers().length, 1); +}); + +test("boundary entries from other extensions are kept", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + const other = { type: "custom", customType: "other", data: 1 }; + const [result] = host.emit("turn_end", { entries: [other], message: {} }) as any[]; + assert.equal(result.entries.length, 2); + assert.equal(result.entries[0], other); +}); + +test("an answer left over after the user aborts is added without restarting the agent", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + // The aborted turn's boundary adds the answer but asks for nothing more. + const aborted = boot(host.session); + await start(aborted); + assert.equal(aborted.sent.length, 1, "control: a fresh idle process would wake"); + + const { host: second } = await withBackgroundForm(); + second.setIdle(false); + second.type(...SUBMIT_TWO); + const boundary = second.turnEnd({ stopReason: "aborted" }); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, false); + + const { host: third } = await withBackgroundForm(); + third.setIdle(false); + third.type(...SUBMIT_TWO); + third.settle(true); + await tick(); + assert.equal(third.sent.length, 1); + assert.deepEqual(third.sent[0]?.options, { triggerTurn: false }); + assert.equal(third.answers().length, 1); +}); + +test("no duplicate delivery after reload, resume or a second session_start", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + host.recordWake(); + host.settle(); + assert.equal(host.sent.length, 1); + + await start(host, "reload"); + host.emit("session_tree"); + host.emit("session_compact"); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.panelText(), ""); + + // A later process on the same session sees the message on the branch. + const later = boot(host.session); + await start(later); + later.turnEnd(); + later.settle(); + await tick(); + assert.deepEqual(later.sent, []); + assert.equal(later.panelText(), ""); + assert.equal(later.answers().length, 1); +}); + +test("an outcome journalled but never recorded is delivered on the next start, once", async () => { + // The process dies after the answer was accepted but before the run wrote it. + const dying = boot(undefined, {}); + await start(dying, "startup"); + const receipt = await dying.askInBackground(); + dying.type(...SUBMIT_TWO); + await tick(); + assert.equal(dying.sent.length, 1); + assert.equal(dying.answers().length, 0); + + const host = boot(dying.session); + await start(host); + await start(host, "reload"); + assert.equal(host.panelText(), "", "an answered form is not shown again"); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, receipt.details.requestId); + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.sent.length, 1); +}); + +test("a cancellation is recorded as context and never wakes or aborts the agent", async () => { + const { host, requestId } = await withBackgroundForm(); + // Dismiss, confirmed because the form has a draft. + host.type(KEY.enter, KEY.ctrlC, KEY.ctrlC); + await tick(); + + assert.equal(host.sent.length, 1); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: false }); + assert.equal( + host.sent[0]?.message.content, + [ + `User cancelled your earlier ask_user form ${requestId} (Storage). Cancellation is not approval; keep risky actions blocked.`, + '- db "Which database?"', + '- cache "Which cache?"', + ].join("\n") + ); + assert.equal(host.isIdle(), true, "no turn was started"); + assert.equal(host.aborts, 0, "unrelated agent work is not aborted"); + assert.equal(host.journal().at(-1).result.status, "cancelled"); + assert.equal(host.panelText(), ""); + + host.settle(); + await start(host, "reload"); + const later = boot(host.session); + await start(later); + assert.equal(host.sent.length, 1); + assert.deepEqual(later.sent, []); + assert.equal(later.panelText(), ""); +}); + +test("a cancellation while the agent works joins the turn boundary without asking for a turn", async () => { + const { host } = await withBackgroundForm(ONE("a")); + await host.askInBackground(ONE("b")); + host.setIdle(false); + host.type(KEY.ctrlC); + await tick(); + assert.match(host.panelText(), /Pick b\?/, "only the cancelled form closed"); + assert.deepEqual(host.sent, []); + assert.equal(host.aborts, 0); + + const boundary = host.turnEnd({ stopReason: "stop" }); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, false); + assert.match(boundary.entries[0].content, /cancelled/); +}); + +test("delivered answers render as a compact card", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + const render = host.renderers.get(ASK_ANSWER_MESSAGE_TYPE); + const theme = { + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + const card = render?.(host.sent[0]?.message, { expanded: false }, theme); + const text = card.render(80).join("\n"); + assert.match(text, /ask_user answered · Storage/); + assert.match(text, /✓ DB: Postgres/); + assert.doesNotMatch(text, /requestId|\{/); + assert.equal(render?.({ details: undefined }, {}, theme), undefined); +}); + +// --- Recovery and branches ------------------------------------------------- + +test("an interrupted form comes back in the panel with its draft and is answered once", async () => { + const session = await interruptedSession(); + const host = boot(session); + const returned = host.emit("session_start", { reason: "resume" }); + assert.deepEqual(returned, [undefined], "the handler returns at once"); + await tick(); + + assert.equal(host.forms.length, 0, "recovery does not block the input"); + assert.match(host.panelText(), /Which cache\?/, "DB came back from the draft"); + assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); + assert.equal(host.notices.length, 1); + assert.equal(host.sent.length, 0); + + host.type(KEY.focus, KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); + assert.match(host.sent[0]?.message.content ?? "", /cache "Which cache\?": Redis/); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); +}); + +test("a form the conversation moved past is not brought back", async () => { + const session = await interruptedSession(); + session.appendMessage({ role: "user", content: "never mind", timestamp: Date.now() }); + const host = boot(session); + await start(host); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + assert.deepEqual(host.sent, []); +}); + +test("a form from another branch is not shown and writes nothing", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + const first = boot(session); + await start(first, "startup"); + await first.askInBackground(); + first.type(KEY.enter); + assert.equal(first.journal().length, 2); + + // Branch B forks from before the form was asked. + session.branch(rootId); + session.appendMessage({ role: "user", content: "other", timestamp: Date.now() }); + const host = boot(session); + await start(host); + host.emit("session_tree"); + await tick(); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + assert.deepEqual(host.sent, []); + assert.deepEqual(host.journal(), []); +}); + +test("a stale form cannot write into the branch the user moved to", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + // Keep hold of the form as it is on screen, as a late callback would. + const stale = host.widgets.get("pi-ask:panel")?.component; + assert.ok(stale); + const handleInput = stale.handleInput?.bind(stale); + + session.branch(rootId); + host.emit("session_tree"); + assert.equal(host.panelText(), "", "the panel follows the branch at once"); + for (const key of SUBMIT_TWO) { + handleInput?.(key); + } + host.type(KEY.focus, ...SUBMIT_TWO); + await tick(); + + assert.deepEqual(host.sent, []); + assert.deepEqual(host.journal(), [], "nothing was written into this branch"); + assert.equal(host.turnEnd().entries.length, 0); + + // Back on the original branch the form is still waiting, unanswered. + const original = boot(session); + session.branch(session.getEntries().at(-1)?.id ?? rootId); + await start(original); + assert.deepEqual(original.sent, []); +}); + +test("the queue is TUI-only and a torn-down runtime writes nothing", async () => { + const session = await interruptedSession(); + const rpc = boot(session, { mode: "rpc" }); + await start(rpc); + assert.equal(rpc.widgets.size, 0); + assert.deepEqual(rpc.sent, []); + + const host = boot(session); + await start(host); + assert.match(host.panelText(), /Which cache\?/); + const panel = host.widgets.get("pi-ask:panel")?.component; + host.emit("session_shutdown", { reason: "quit" }); + assert.equal(host.widgets.size, 0); + panel?.handleInput?.(KEY.enter); + panel?.handleInput?.(KEY.enter); + host.type(KEY.focus); + await tick(); + assert.deepEqual(host.sent, []); + assert.deepEqual(kinds(host), ["form", "draft"]); + assert.equal(host.turnEnd().entries.length, 0); +}); diff --git a/pi-ask/tests/outbox.test.ts b/pi-ask/tests/outbox.test.ts new file mode 100644 index 00000000..182338e1 --- /dev/null +++ b/pi-ask/tests/outbox.test.ts @@ -0,0 +1,136 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { formatDeliveredOutcome } from "../src/delivery.ts"; +import { + type AskDeliveryItem, + boundaryContinues, + planDelivery, +} from "../src/state/outbox.ts"; +import type { AskResult } from "../src/types.ts"; + +const item = ( + outcomeId: string, + overrides: Partial = {} +): AskDeliveryItem => ({ + outcomeId, + cancelled: false, + inFlight: false, + ...overrides, +}); + +const actions = (...args: Parameters) => + planDelivery(...args).map((step) => step.action); + +test("an idle agent is woken by an answer; a working one is left alone until a boundary", () => { + assert.deepEqual(actions([item("a")], { trigger: "now", idle: true }), ["wake"]); + assert.deepEqual(actions([item("a")], { trigger: "now", idle: false }), ["hold"]); + assert.deepEqual(actions([item("a")], { trigger: "boundary", idle: false }), [ + "propose", + ]); +}); + +test("a cancellation never wakes: appended when idle, proposed at a boundary", () => { + const cancelled = [item("a", { cancelled: true })]; + assert.deepEqual(actions(cancelled, { trigger: "now", idle: true }), ["append"]); + assert.deepEqual(actions(cancelled, { trigger: "settled", idle: false }), ["append"]); + assert.deepEqual(actions(cancelled, { trigger: "now", idle: false }), ["hold"]); + assert.deepEqual(actions(cancelled, { trigger: "boundary", idle: false }), [ + "propose", + ]); + assert.equal(boundaryContinues(cancelled), false); +}); + +test("an outcome already on its way is never sent again, whatever happens next", () => { + const flying = [item("a", { inFlight: true })]; + for (const trigger of ["now", "boundary", "settled"] as const) { + for (const idle of [true, false]) { + assert.deepEqual(actions(flying, { trigger, idle }), ["hold"]); + assert.deepEqual(actions(flying, { trigger, idle, aborted: true }), ["hold"]); + } + } +}); + +test("a settled run is idle whatever the host reports; after an abort nothing wakes", () => { + assert.deepEqual(actions([item("a")], { trigger: "settled", idle: false }), ["wake"]); + assert.deepEqual( + actions([item("a"), item("b")], { trigger: "settled", idle: true, aborted: true }), + ["append", "append"] + ); +}); + +test("one wake per batch, in request order; the rest join at its first boundary", () => { + const steps = planDelivery( + [item("c", { cancelled: true }), item("a"), item("b"), item("d", { cancelled: true })], + { trigger: "now", idle: true } + ); + assert.deepEqual(steps, [ + { outcomeId: "c", action: "append" }, + { outcomeId: "a", action: "wake" }, + { outcomeId: "b", action: "hold" }, + { outcomeId: "d", action: "hold" }, + ]); +}); + +test("an answer at a boundary asks for one more request, unless the turn was aborted or failed", () => { + assert.equal(boundaryContinues([item("a")]), true); + assert.equal(boundaryContinues([item("a")], "stop"), true); + assert.equal(boundaryContinues([item("a")], "toolUse"), true); + assert.equal(boundaryContinues([item("a")], "aborted"), false); + assert.equal(boundaryContinues([item("a")], "error"), false); + assert.equal( + boundaryContinues([item("c", { cancelled: true }), item("a")]), + true + ); + assert.equal(boundaryContinues([]), false); +}); + +const RESULT: AskResult = { + title: "Storage", + status: "submitted", + requestId: "ask-1", + questions: [ + { id: "db", label: "DB", prompt: "Which\n database?", type: "single" }, + { id: "extras", label: "Extras", prompt: "Extras?", type: "multi" }, + { id: "why", label: "Why", prompt: "Why?", type: "text" }, + { id: "skip", label: "Skip", prompt: "Anything else?", type: "text" }, + ], + answers: { + db: { values: ["pg"], labels: ["Postgres"], note: "for now" }, + extras: { + values: ["a", "b"], + labels: ["Alpha", "Beta"], + optionNotes: { b: "only\nin prod" }, + customText: "and gamma", + }, + why: { values: [], labels: [], customText: "it is boring" }, + }, + unanswered: ["skip"], +}; + +test("a delivered answer names the request and every question by id and prompt", () => { + assert.equal( + formatDeliveredOutcome(RESULT), + [ + "User answered your earlier ask_user form ask-1 (Storage):", + '- db "Which database?": Postgres [pg]; note: for now', + '- extras "Extras?": Alpha [a]; Beta [b] (note: only in prod); wrote "and gamma"', + '- why "Why?": wrote "it is boring"', + '- skip "Anything else?": (no answer)', + ].join("\n") + ); +}); + +test("a delivered cancellation lists what was asked and none of the draft", () => { + const text = formatDeliveredOutcome({ ...RESULT, status: "cancelled", title: undefined }); + assert.equal( + text, + [ + "User cancelled your earlier ask_user form ask-1. Cancellation is not approval; keep risky actions blocked.", + '- db "Which database?"', + '- extras "Extras?"', + '- why "Why?"', + '- skip "Anything else?"', + ].join("\n") + ); + assert.doesNotMatch(text, /Postgres|boring/); +}); diff --git a/pi-ask/tests/recovery.test.ts b/pi-ask/tests/recovery.test.ts deleted file mode 100644 index 92feb5fd..00000000 --- a/pi-ask/tests/recovery.test.ts +++ /dev/null @@ -1,324 +0,0 @@ -import assert from "node:assert/strict"; -import test, { beforeEach } from "node:test"; -import { SessionManager } from "@earendil-works/pi-coding-agent"; -import { registerAskTool } from "../src/ask-tool.ts"; -import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; -import { registerAskRecovery } from "../src/recovery.ts"; -import { createAskRuntime } from "../src/runtime.ts"; -import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; - -const PARAMS = { - title: "Storage", - questions: [ - { - id: "db", - label: "DB", - prompt: "Which database?", - options: [ - { value: "pg", label: "Postgres" }, - { value: "sqlite", label: "SQLite" }, - ], - }, - { - id: "cache", - label: "Cache", - prompt: "Which cache?", - options: [ - { value: "redis", label: "Redis" }, - { value: "none", label: "None" }, - ], - }, - ], -}; - -/** One Pi process: the extension wired as `src/index.ts` wires it. */ -function boot(session?: SessionManager, options?: { mode?: string }) { - const host = fakePi(session, options); - const runtime = createAskRuntime(host.pi); - registerAskTool(host.pi, { runtime }); - const recovery = registerAskRecovery(host.pi, runtime); - const ask = () => - host.tools[0].execute("call-1", PARAMS, undefined, () => {}, host.ctx); - return { ...host, recovery, ask }; -} - -/** A session whose foreground form was open, DB answered, when Pi died. */ -async function interruptedSession() { - const first = boot(); - first.ask().catch(() => {}); - await tick(); - first.forms[0]?.press(KEY.enter); - assert.deepEqual( - first.journal().map((entry) => entry.kind), - ["form", "draft"] - ); - return first.session; -} - -async function start(host: ReturnType, reason = "resume") { - host.emit("session_start", { reason }); - await tick(); -} - -function kinds(host: ReturnType) { - return host.journal().map((entry) => entry.kind); -} - -beforeEach(quietConfig); - -test("a tool call journals the form before waiting and the outcome before returning", async () => { - const host = boot(); - const pending = host.ask(); - await tick(); - assert.deepEqual(kinds(host), ["form"]); - assert.equal(host.journal()[0].mode, "foreground"); - assert.equal(host.journal()[0].toolCallId, "call-1"); - - host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); - const response = await pending; - const outcome = host.journal().at(-1); - assert.equal(outcome.kind, "outcome"); - assert.equal(outcome.channel, "tool"); - assert.equal(response.details.status, "submitted"); - assert.equal(response.details.requestId, host.journal()[0].requestId); - assert.deepEqual(outcome.result, response.details); - - // Nothing is left to recover and nothing is sent twice. - await start(host, "reload"); - assert.equal(host.forms.length, 1); - assert.deepEqual(host.sent, []); -}); - -test("non-interactive and dialog hosts journal a settled outcome", async () => { - const host = boot(undefined, { mode: "json" }); - const response = await host.tools[0].execute( - "call-1", - PARAMS, - undefined, - () => {}, - { mode: "json", hasUI: false } - ); - assert.equal(response.details.status, "unavailable"); - assert.deepEqual(kinds(host), ["form", "outcome"]); - assert.equal(response.details.requestId, host.journal()[0].requestId); -}); - -test("an interrupted form reopens with its draft and its answer reaches the agent once", async () => { - const session = await interruptedSession(); - const host = boot(session); - const returned = host.emit("session_start", { reason: "resume" }); - assert.deepEqual( - returned, - [undefined], - "the handler returns at once instead of waiting for the form" - ); - await tick(); - assert.equal(host.forms.length, 1); - assert.equal(host.notices.length, 1); - assert.equal(host.sent.length, 0, "nothing is delivered while open"); - - // DB came back from the draft; only Cache and the review tab remain. - host.forms[0]?.press(KEY.enter, KEY.enter); - await tick(); - - assert.equal(host.sent.length, 1); - const [{ message, options }] = host.sent; - assert.equal(message.customType, ASK_ANSWER_MESSAGE_TYPE); - assert.deepEqual(options, { triggerTurn: true }); - assert.match(message.content, /ask-[0-9a-f]{8} \(Storage\)/); - assert.match(message.content, /DB: Postgres\nCache: Redis/); - assert.equal(message.details.result.status, "submitted"); - assert.deepEqual(kinds(host), [ - "form", - "draft", - "draft", - "outcome", - "delivered", - ]); - assert.equal(host.journal().at(-2).channel, "message"); -}); - -test("no duplicate delivery after a second session_start", async () => { - const session = await interruptedSession(); - const host = boot(session); - await start(host); - host.forms[0]?.press(KEY.enter, KEY.enter); - await tick(); - assert.equal(host.sent.length, 1); - - await start(host, "reload"); - host.emit("session_tree"); - await tick(); - assert.equal(host.forms.length, 1); - assert.equal(host.sent.length, 1); - - // A later process on the same session sees the marker too. - const later = boot(session); - await start(later); - assert.equal(later.forms.length, 0); - assert.deepEqual(later.sent, []); -}); - -test("the delivery marker alone prevents a second delivery", async () => { - const session = await interruptedSession(); - // A working agent queues the message, so it is not in the session yet. - const host = fakePi(session, { persistSentMessages: false }); - const runtime = createAskRuntime(host.pi); - registerAskRecovery(host.pi, runtime); - host.setIdle(false); - host.emit("session_start", { reason: "resume" }); - await tick(); - host.forms[0]?.press(KEY.enter, KEY.enter); - await tick(); - assert.deepEqual(host.sent[0]?.options, { - triggerTurn: true, - deliverAs: "steer", - }); - - const later = boot(session); - await start(later); - assert.equal(later.forms.length, 0); - assert.deepEqual(later.sent, []); -}); - -test("an outcome journalled but never sent is delivered on the next start, once", async () => { - const session = await interruptedSession(); - const dying = fakePi(session); - const requestId = dying.journal()[0].requestId; - createAskRuntime(dying.pi).journal.recordOutcome( - requestId, - { - status: "submitted", - title: "Storage", - questions: [], - answers: {}, - unanswered: [], - }, - "message" - ); - - const host = boot(session); - await start(host); - await start(host, "reload"); - assert.equal(host.forms.length, 0, "an answered form is not reopened"); - assert.equal(host.sent.length, 1); - assert.equal(host.sent[0]?.message.details.requestId, requestId); -}); - -test("a cancelled recovery is recorded, never wakes the agent and does not reopen", async () => { - const session = await interruptedSession(); - const host = boot(session); - await start(host); - // The restored draft makes the form dirty: cancel asks to confirm. - host.forms[0]?.press(KEY.escape, KEY.escape); - await tick(); - - assert.equal(host.sent.length, 1); - assert.deepEqual(host.sent[0]?.options, { triggerTurn: false }); - assert.match(host.sent[0]?.message.content ?? "", /cancelled/); - assert.match(host.sent[0]?.message.content ?? "", /not approval/); - assert.equal(host.journal().at(-2).result.status, "cancelled"); - - await start(host, "reload"); - const later = boot(session); - await start(later); - assert.equal(host.forms.length, 1); - assert.equal(later.forms.length, 0); - assert.equal(later.sent.length, 0); -}); - -test("a stale form from another branch is ignored", async () => { - const session = SessionManager.inMemory(); - const rootId = session.appendMessage({ - role: "user", - content: "start", - timestamp: Date.now(), - }); - // Branch A: a form interrupted mid-answer. - const first = boot(session); - first.ask().catch(() => {}); - await tick(); - first.forms[0]?.press(KEY.enter); - assert.equal(first.journal().length, 2); - - // Branch B forks from before the form was asked. - session.branch(rootId); - session.appendMessage({ role: "user", content: "other", timestamp: Date.now() }); - const host = boot(session); - await start(host); - host.emit("session_tree"); - await tick(); - assert.equal(host.forms.length, 0); - assert.deepEqual(host.sent, []); - assert.deepEqual(host.journal(), []); -}); - -test("an answer is dropped when the branch changes while the form is open", async () => { - const session = SessionManager.inMemory(); - const rootId = session.appendMessage({ - role: "user", - content: "start", - timestamp: Date.now(), - }); - const first = boot(session); - first.ask().catch(() => {}); - await tick(); - - const host = boot(session); - await start(host); - assert.equal(host.forms.length, 1); - - session.branch(rootId); - host.emit("session_tree"); - host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); - await tick(); - - assert.deepEqual(host.sent, []); - assert.deepEqual( - host.journal(), - [], - "nothing from the other branch's form is written into this one" - ); -}); - -test("a form the conversation moved past is not reopened", async () => { - const session = await interruptedSession(); - session.appendMessage({ role: "user", content: "never mind", timestamp: Date.now() }); - const host = boot(session); - await start(host); - assert.equal(host.forms.length, 0); - assert.deepEqual(host.sent, []); -}); - -test("a form that is open in this process is not treated as interrupted", async () => { - const host = boot(); - const pending = host.ask(); - await tick(); - host.emit("session_tree"); - await start(host, "reload"); - assert.equal(host.forms.length, 1); - - host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); - assert.equal((await pending).details.status, "submitted"); - assert.deepEqual(host.sent, []); -}); - -test("recovery is TUI-only and stops at session shutdown", async () => { - const session = await interruptedSession(); - const rpc = boot(session, { mode: "rpc" }); - await start(rpc); - assert.equal(rpc.forms.length, 0); - assert.deepEqual(rpc.sent, []); - - const host = boot(session); - await start(host); - assert.equal(host.forms.length, 1); - host.emit("session_shutdown", { reason: "quit" }); - host.forms[0]?.press(KEY.enter, KEY.enter); - await tick(); - assert.deepEqual(host.sent, [], "a torn-down runtime writes nothing"); - assert.deepEqual(kinds(host), ["form", "draft"]); - - await start(host); - assert.equal(host.forms.length, 1); -}); diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts index 7b9ea328..65b76338 100644 --- a/pi-ask/tests/support/fake-pi.ts +++ b/pi-ask/tests/support/fake-pi.ts @@ -1,7 +1,17 @@ /** * A fake Pi host for lifecycle tests: a real in-memory SessionManager (so - * branches behave as they do in Pi), recorded sendMessage calls, and a - * `ui.custom` that exposes the open form for scripted key presses. + * branches behave as they do in Pi), a TUI reduced to keyboard focus, widgets + * and modal forms, and `sendMessage` with Pi's delivery rules. + * + * What is modelled on Pi 1.4.0, because the tests depend on it: + * - `sendMessage` with `triggerTurn` while idle starts a run at once, but the + * message is written to the session only when that run records it + * (`recordWake`). Without `triggerTurn` it is appended now when idle, and + * at the end of the turn when busy. + * - `turn_end` and `agent_before_settle` handlers return entries that are + * appended as soon as the dispatch ends. + * - A widget is a component above or below the editor; it gets keys only + * while it has TUI focus. A modal form takes focus and gives it back. */ import { SessionManager } from "@earendil-works/pi-coding-agent"; import { DEFAULT_ASK_CONFIG } from "../../src/config/defaults.ts"; @@ -9,11 +19,21 @@ import { getAskConfigStore } from "../../src/config/store.ts"; import { ASK_JOURNAL_ENTRY_TYPE } from "../../src/journal/entries.ts"; import type { AskResult } from "../../src/types.ts"; -export const KEY = { enter: "\r", escape: "\u001b" }; +export const KEY = { + enter: "\r", + escape: "\u001b", + ctrlC: "\u0003", + /** Default `global.later`. */ + later: "\u000c", + /** Default `global.panelFocus` (alt+a). */ + focus: "\u001ba", + down: "\u001b[B", +}; export interface OpenForm { done: (result: AskResult) => void; press: (...keys: string[]) => void; + render: () => string; } export interface SentMessage { @@ -26,6 +46,13 @@ export interface SentMessage { options?: { deliverAs?: string; triggerTurn?: boolean }; } +interface FakeComponent { + dispose?: () => void; + focused?: boolean; + handleInput?: (data: string) => void; + render?: (width: number) => string[]; +} + export function quietConfig() { getAskConfigStore().setConfig({ ...DEFAULT_ASK_CONFIG, @@ -40,10 +67,60 @@ export function fakePi( ) { const handlers = new Map unknown>>(); const tools: any[] = []; + const commands = new Map(); + const renderers = new Map any>(); const sent: SentMessage[] = []; const forms: OpenForm[] = []; const notices: string[] = []; + const widgets = new Map< + string, + { component?: FakeComponent; lines?: string[]; placement: string } + >(); + const inputListeners = new Set<(data: string) => any>(); + // Messages the host has accepted but not yet written to the session. + const wakes: SentMessage["message"][] = []; + const heldCustom: SentMessage["message"][] = []; let idle = true; + let aborts = 0; + + const editor: FakeComponent & { text: string } = { + text: "", + focused: true, + handleInput(data) { + editor.text += data; + }, + }; + let focus: FakeComponent | null = editor; + const tui = { + requestRender() {}, + getFocusedComponent: () => focus, + setFocus(component: FakeComponent | null) { + if (focus && "focused" in focus) { + focus.focused = false; + } + focus = component; + if (component && "focused" in component) { + component.focused = true; + } + }, + }; + const theme = { + bg: (_color: string, text: string) => text, + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + + function persist(message: SentMessage["message"]) { + if (options.persistSentMessages === false) { + return; + } + session.appendCustomMessageEntry( + message.customType, + message.content, + message.display, + structuredClone(message.details) + ); + } const pi = { on(event: string, handler: (...args: any[]) => unknown) { @@ -53,55 +130,121 @@ export function fakePi( registerTool(tool: unknown) { tools.push(tool); }, + registerCommand(name: string, command: unknown) { + commands.set(name, command); + }, + registerMessageRenderer(type: string, renderer: (...args: any[]) => any) { + renderers.set(type, renderer); + }, appendEntry(customType: string, data: unknown) { session.appendCustomEntry(customType, structuredClone(data)); }, sendMessage(message: SentMessage["message"], sendOptions: any) { sent.push({ message, options: sendOptions }); - if (options.persistSentMessages !== false) { - session.appendCustomMessageEntry( - message.customType, - message.content, - message.display, - structuredClone(message.details) - ); + if (sendOptions?.triggerTurn) { + if (idle) { + idle = false; + wakes.push(message); + } else { + heldCustom.push(message); + } + } else if (idle) { + persist(message); + } else { + heldCustom.push(message); } }, }; + const ui = { + theme, + notify(text: string) { + notices.push(text); + }, + setWorkingVisible() {}, + getEditorText: () => editor.text, + onTerminalInput(listener: (data: string) => any) { + inputListeners.add(listener); + return () => inputListeners.delete(listener); + }, + setWidget(key: string, content: any, widgetOptions?: any) { + widgets.get(key)?.component?.dispose?.(); + widgets.delete(key); + if (content === undefined) { + return; + } + const placement = widgetOptions?.placement ?? "aboveEditor"; + widgets.set( + key, + typeof content === "function" + ? { placement, component: content(tui, theme) } + : { placement, lines: content } + ); + }, + custom(factory: (...args: any[]) => any) { + return new Promise((resolve) => { + const done = (result: AskResult) => { + if (focus === component) { + tui.setFocus(editor); + } + resolve(result); + }; + const component = factory(tui, theme, {}, done); + tui.setFocus(component); + forms.push({ + done, + press: (...keys) => { + for (const key of keys) { + component.handleInput(key); + } + }, + render: () => component.render(80).join("\n"), + }); + }); + }, + }; + const ctx = { cwd: process.cwd(), mode: options.mode ?? "tui", hasUI: true, sessionManager: session, isIdle: () => idle, - ui: { - notify(text: string) { - notices.push(text); - }, - setWorkingVisible() {}, - custom(factory: (...args: any[]) => any) { - return new Promise((resolve) => { - const tui = { requestRender() {} }; - const theme = { - bg: (_color: string, text: string) => text, - fg: (_color: string, text: string) => text, - bold: (text: string) => text, - }; - const component = factory(tui, theme, {}, resolve); - forms.push({ - done: resolve, - press: (...keys) => { - for (const key of keys) { - component.handleInput(key); - } - }, - }); - }); - }, + abort() { + aborts++; }, + ui, }; + function emit(event: string, payload: Record = {}) { + return (handlers.get(event) ?? []).map((handler) => + handler({ type: event, ...payload }, ctx) + ); + } + + /** An actionable boundary: handlers chain entries, Pi appends them. */ + function boundary(event: string, payload: Record = {}) { + let entries: any[] = []; + let proceed = false; + for (const handler of handlers.get(event) ?? []) { + const result = handler( + { type: event, ...payload, entries, continue: proceed }, + ctx + ) as { entries?: any[]; continue?: boolean } | undefined; + entries = result?.entries ?? entries; + proceed = result?.continue ?? proceed; + } + for (const entry of entries) { + if (entry.type === "custom_message") { + persist(entry); + } + } + for (const message of heldCustom.splice(0)) { + persist(message); + } + return { entries, continue: proceed }; + } + return { pi: pi as never, ctx: ctx as never, @@ -110,15 +253,69 @@ export function fakePi( forms, notices, tools, + commands, + renderers, + widgets, + editor, + get aborts() { + return aborts; + }, setIdle(value: boolean) { idle = value; }, + isIdle: () => idle, /** Dispatch a lifecycle event; returns what the handlers returned. */ - emit(event: string, payload: Record = {}) { - return (handlers.get(event) ?? []).map((handler) => - handler({ type: event, ...payload }, ctx) + emit, + /** The run started by an idle wake writes its starting message. */ + recordWake() { + for (const message of wakes.splice(0)) { + persist(message); + } + }, + turnEnd: (message: Record = { stopReason: "toolUse" }) => + boundary("turn_end", { message }), + beforeSettle: () => boundary("agent_before_settle"), + /** The run is over: Pi is idle and tells the extensions. */ + settle(aborted = false) { + idle = true; + return emit("agent_settled", { aborted }); + }, + /** A key from the terminal: listeners first, then the focused component. */ + type(...keys: string[]) { + for (const key of keys) { + let consumed = false; + for (const listener of inputListeners) { + if (listener(key)?.consume) { + consumed = true; + break; + } + } + if (!consumed) { + focus?.handleInput?.(key); + } + } + }, + focusIs(target: "editor" | "panel" | "form"): boolean { + const panel = widgets.get("pi-ask:panel")?.component; + if (target === "editor") { + return focus === editor; + } + if (target === "panel") { + return !!panel && focus === panel; + } + return !!focus && focus !== editor && focus !== panel; + }, + panelText() { + return ( + widgets.get("pi-ask:panel")?.component?.render?.(80).join("\n") ?? "" ); }, + indicator() { + return widgets.get("pi-ask:pending")?.lines?.join("\n"); + }, + command(name: string, args = "") { + return commands.get(name)?.handler(args, ctx); + }, journal() { return session .getBranch() @@ -129,6 +326,12 @@ export function fakePi( ) .map((entry: any) => entry.data); }, + /** `pi-ask:answer` messages written to the active branch. */ + answers(): any[] { + return session + .getBranch() + .filter((entry: any) => entry.type === "custom_message"); + }, }; } diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 3faecd05..ea2d35a5 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,9 +2,9 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "recovery.test.ts"], - commands: ["answer", "ask-settings"], tools: ["ask_user"], - hooks: ["session_start", "session_tree", "session_shutdown"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts"], + commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], + hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled"], }, "pi-automode": { name: "@gagansd/pi-automode", tests: "tests", From ad9311f4e912970e4d3d96b5369d291ef7bfb8b1 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:50 +0000 Subject: [PATCH 11/38] feat(ask): register the background field and add its settings toggle `background` is now part of the registered schema when `behaviour.background` is on (384 est. tokens, up from 376). With it off the field is absent and a stale call that still carries it blocks. /ask-settings gains a "Background questions" toggle under "After /reload", since schema settings never change mid-session. --- pi-ask/src/features.ts | 2 +- pi-ask/src/ui/settings-list.ts | 10 +++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/pi-ask/src/features.ts b/pi-ask/src/features.ts index 0a262e2b..be54a6f9 100644 --- a/pi-ask/src/features.ts +++ b/pi-ask/src/features.ts @@ -23,7 +23,7 @@ export const ALL_ASK_FEATURES: AskFeatures = { * change that makes the tool honour the field; config can only narrow this. */ export const SHIPPED_ASK_FEATURES: AskFeatures = { - background: false, + background: true, expiry: false, }; diff --git a/pi-ask/src/ui/settings-list.ts b/pi-ask/src/ui/settings-list.ts index d5d5d090..fc2a3674 100644 --- a/pi-ask/src/ui/settings-list.ts +++ b/pi-ask/src/ui/settings-list.ts @@ -34,7 +34,7 @@ const DESCRIPTION_LINE_COUNT = 3; const COMPACT_WIDTH = 40; const RESET_CONFIRMATION_MS = 2000; -type SettingSection = "Actions" | "Live settings"; +type SettingSection = "Actions" | "Live settings" | "After /reload"; type ToggleSettingKey = keyof AskConfig["behaviour"] | "notifications.enabled"; interface BaseSetting { @@ -95,6 +95,14 @@ const SETTINGS = [ label: "Show footer hints", type: "toggle", }, + { + description: + "Let the agent ask a question in the background and keep working while it waits. Changing this takes effect after /reload.", + key: "background", + section: "After /reload", + label: "Background questions", + type: "toggle", + }, { description: "Reset behaviour, keymaps, notifications, and extraction settings to defaults. Press twice quickly to confirm.", From 56af54fc0335e5139c9cc1226e6a37f929bf37f2 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:49:58 +0000 Subject: [PATCH 12/38] docs(ask): describe the panel, answer later and background delivery --- pi-ask/README.md | 32 +++++++++++++++++++++++++++----- pi-ask/skills/ask-user/SKILL.md | 2 ++ 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/pi-ask/README.md b/pi-ask/README.md index 4f8b64c9..ff165712 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -32,6 +32,24 @@ The agent calls `ask_user`. `/answer` if it asked in prose instead. | Type freely | `text`, or **Type your own** on a choice question | | Understand a choice first | Notes | | The question is the wrong shape | `t` switches `single` ↔ `multi` | +| Answer later | `Ctrl+L` on a blocking form. The agent carries on; the form waits in the panel | + +### Questions that do not block + +A background question, a form you deferred, and a form left open when Pi last stopped all wait in one queue, shown one at a time in the order they were asked. The form sits in a panel above the input. Your message draft is untouched and you can keep typing and sending. + +| Key | What it does | +| --- | --- | +| `Alt+A` | Move the keyboard between the panel and the input. Reopens a hidden panel | +| `Esc` or `Ctrl+L` in the panel | Hide the panel. Nothing is cancelled | +| `Ctrl+C` in the panel | Cancel that form only. The agent's other work is not interrupted | + +- A new question takes the keyboard only when the input is empty. A hidden panel stays hidden; a line under the input counts what is waiting. +- A blocking question takes over while it is open. The panel returns afterwards as it was. +- Your answer joins a working agent at its next turn boundary and wakes an idle one. A cancellation is added to the conversation but never starts a turn; neither does an answer left over after you abort the run. +- Queue, drafts and whether the panel is hidden follow the active session branch. + +Both keys are `keymaps.global.later` and `keymaps.global.panelFocus` in the config file. ### Commands @@ -39,8 +57,9 @@ The agent calls `ask_user`. `/answer` if it asked in prose instead. | --- | --- | | `/answer` | Turn the latest completed assistant message into a form | | `/ask-settings` | Settings overlay. `?` inside a form opens the same overlay | +| `/ask-panel` | Show the waiting questions and move the keyboard to them | -Hosts without the custom TUI (RPC subagents, ACP clients) get the same interview as sequential select/input cards with back navigation and a review card. Callers with no dialog UI at all get `status: "unavailable"`. +Hosts without the custom TUI (RPC subagents, ACP clients) get the same interview as sequential select/input cards with back navigation and a review card; a background call blocks there, and there is no "answer later". Callers with no dialog UI at all get `status: "unavailable"`. ## Contract @@ -60,11 +79,14 @@ Output: - `answers[id]`: `{ values, labels, customText?, note?, optionNotes? }` - `unanswered: id[]` - `requestId`: ties a receipt to the answer delivered later +- `pending`: forms waiting, this one included (`queued` only) - `expired: id[]`: answers that are auto-applied fallbacks `queued` (background call) and `deferred` (you chose "answer later") are receipts, not answers. `expired` means nobody responded: a fallback is the agent's assumption, never approval. The rules ride in those results, so they cost context only when they happen. -Every form, draft and outcome is journalled in the session. A form left open when Pi quit reopens on startup, resume or fork with its draft, and its answer reaches the agent once. The journal follows the active branch. +The later answer is a `pi-ask:answer` message that names the request and each question by id and prompt, so it stands without the original call in context. + +Every form, draft and outcome is journalled in the session. A form left open when Pi quit comes back in the panel on startup, resume or fork with its draft, and its answer reaches the agent once: delivery is decided from what the active branch already holds. The journal follows the active branch. Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the current chat model unless `answer.extractionModels` is set. `PI_ASK_LOCALE=zh` localizes the dialog cards and result summaries (Simplified Chinese). @@ -76,7 +98,7 @@ Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the curren Schema settings apply on `/reload`, not live. A disabled field is absent from the schema, not ignored. -> Unreleased: `background`, `timeoutSeconds`, `fallback` and the `queued` / `deferred` / `expired` statuses are the 0.2.0 contract and are not registered yet. +> Unreleased: this is the 0.2.0 contract. `background`, `queued` and `deferred` work on this branch; `timeoutSeconds`, `fallback` and `expired` are not registered yet. ## Context footprint @@ -87,8 +109,8 @@ Recurring model-facing contribution of `ask_user`, measured with `npm run tokens | description | 148 | 37 | | prompt snippet | 103 | 26 | | prompt guidelines | 723 | 181 | -| parameter schema | 528 | 132 | -| **total** | **1,502** | **376** | +| parameter schema | 560 | 140 | +| **total** | **1,534** | **384** | Field-level prose lives in the guidelines; the registered schema ships without `description` keys. diff --git a/pi-ask/skills/ask-user/SKILL.md b/pi-ask/skills/ask-user/SKILL.md index 20d3b117..84c28506 100644 --- a/pi-ask/skills/ask-user/SKILL.md +++ b/pi-ask/skills/ask-user/SKILL.md @@ -11,4 +11,6 @@ Ask one decision per question. Cancellation or ambiguity is not approval; keep r `single` one choice, `multi` several, `text` free input. Unique `id`s. Recommended options get a `description`; never preselect. Typed text is not an option value. +If the schema has `background`, set it when you can keep working without the answer. The result is then a receipt, not an answer; the answer arrives later as a message. Do not ask again. + Settings: `/ask-settings` or `?` in a form. Optional file: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the current chat model unless `answer.extractionModels` is set. From d288b53d8eb7f9b5513824aeac8d5e59d32bbcdd Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:57:43 +0000 Subject: [PATCH 13/38] feat(ask): add pure expiry clock and fallback rules The countdown only starts when the form is armed and on screen, and can only stop: interaction, hiding, or expiry end it for good. Time and timers are injected. Fallbacks apply only to declared, unanswered questions. --- pi-ask/src/i18n.ts | 10 +- pi-ask/src/result-format.ts | 11 +- pi-ask/src/state/expiry.ts | 256 ++++++++++++++++++++++++++++++++ pi-ask/src/types.ts | 4 + pi-ask/tests/contract.test.ts | 4 +- pi-ask/tests/expiry.test.ts | 266 ++++++++++++++++++++++++++++++++++ 6 files changed, 546 insertions(+), 5 deletions(-) create mode 100644 pi-ask/src/state/expiry.ts create mode 100644 pi-ask/tests/expiry.test.ts diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index 12198941..8785156b 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -33,6 +33,8 @@ export interface AskStrings { queuedSummary: (requestId: string, pending?: number) => string; /** Receipt returned to the model when the user chose "answer later". */ deferredSummary: (requestId: string) => string; + /** Appended to an answer the tool applied itself after the limit lapsed. */ + fallbackMark: string; /** Trailer returned to the model after the time limit lapsed. */ expiredSummary: (fallbackLabels: string[]) => string; /** Heading of the follow-up message that carries a late answer. */ @@ -97,13 +99,14 @@ const EN_STRINGS: AskStrings = { }. ${EN_RECEIPT_RULES}`, deferredSummary: (requestId) => `User will answer later (${requestId}). ${EN_RECEIPT_RULES}`, + fallbackMark: "[fallback: not chosen by the user]", expiredSummary: (fallbackLabels) => [ - "No response within the time limit.", + "The user did not respond within the time limit.", fallbackLabels.length > 0 ? `Fallback applied for: ${fallbackLabels.join(", ")}.` : "No fallback was applied.", - "A fallback is your own assumption, not user approval; keep irreversible actions blocked. The user may still correct it.", + "A fallback is your own assumption, not user approval; keep irreversible and risky actions blocked. The user may still correct it.", ].join(" "), answerDelivered: (requestId, title) => `User answered your earlier ask_user form ${formRef(requestId, title)}:`, @@ -151,13 +154,14 @@ const ZH_STRINGS: AskStrings = { }。${ZH_RECEIPT_RULES}`, deferredSummary: (requestId) => `用户稍后回答(${requestId})。${ZH_RECEIPT_RULES}`, + fallbackMark: "[备选项:并非用户所选]", expiredSummary: (fallbackLabels) => [ "用户未在时限内回应。", fallbackLabels.length > 0 ? `已对以下问题应用备选项:${fallbackLabels.join("、")}。` : "没有应用任何备选项。", - "备选项只是你自己的假设,不是用户批准;不可逆的操作仍须保持阻止。用户之后仍可更正。", + "备选项只是你自己的假设,不是用户批准;不可逆和有风险的操作仍须保持阻止。用户之后仍可更正。", ].join(""), answerDelivered: (requestId, title) => `用户回答了你之前的 ask_user 表单 ${formRef(requestId, title)}:`, diff --git a/pi-ask/src/result-format.ts b/pi-ask/src/result-format.ts index 4e5b9547..054c2559 100644 --- a/pi-ask/src/result-format.ts +++ b/pi-ask/src/result-format.ts @@ -1,3 +1,4 @@ +import { askStrings } from "./i18n.ts"; import { isCustomOnlyAnswer } from "./state/answers.ts"; import type { AskResult } from "./types.ts"; @@ -8,6 +9,7 @@ export function formatResultLines( const lines: string[] = []; let hasPresentationOverride = false; + const fallbacks = new Set(result.expired ?? []); for (const question of result.questions) { const answer = result.answers[question.id]; @@ -18,7 +20,9 @@ export function formatResultLines( const answerLine = formatAnswerLine(question.label, answer, options.mode); lines.push( - answerLine ?? formatUnansweredLine(question.label, options.mode) + answerLine + ? markFallback(answerLine, fallbacks.has(question.id)) + : formatUnansweredLine(question.label, options.mode) ); if (hasPresentedTypeOverride(question.type, question.presentedType)) { @@ -44,6 +48,11 @@ export function formatResultLines( return lines; } +/** An auto-applied answer says so on its own line, wherever it is read. */ +function markFallback(line: string, isFallback: boolean): string { + return isFallback ? `${line} ${askStrings().fallbackMark}` : line; +} + function formatUnansweredLine( questionLabel: string, mode: "summary" | "render" diff --git a/pi-ask/src/state/expiry.ts b/pi-ask/src/state/expiry.ts new file mode 100644 index 00000000..7f77ac92 --- /dev/null +++ b/pi-ask/src/state/expiry.ts @@ -0,0 +1,256 @@ +/** + * Expiry rules as pure logic: the countdown clock and the fallback answers. + * + * The clock is conservative by construction. It runs only while the form is + * on screen (and the "question waiting" notification has fired), and it can + * only ever stop, never restart: + * + * - any key the form receives stops it (the user is here); + * - putting the form away (panel hidden, another form on top) stops it; + * - once stopped or expired it stays that way. + * + * Time and timers are injected, so every rule is tested without waiting. + */ +import type { AskQuestion, AskResult, AskState } from "../types.ts"; +import { isAnswerAnswered } from "./answers.ts"; +import { toAskResult } from "./result.ts"; + +/** Why a countdown that had not expired will never fire. */ +export type ExpiryStopReason = + /** The user touched the form (a key, or opening it on purpose). */ + | "interaction" + /** The form left the screen before it ran out. */ + | "hidden"; + +export type ExpiryPhase = "pending" | "running" | "stopped" | "expired"; + +export interface ExpiryView { + phase: ExpiryPhase; + /** Whole seconds left; only meaningful while `running`. */ + remainingSeconds: number; + stopReason?: ExpiryStopReason; +} + +export interface ExpiryClock { + clearTimeout(handle: unknown): void; + now(): number; + setTimeout(task: () => void, ms: number): unknown; +} + +export const systemClock: ExpiryClock = { + now: () => Date.now(), + setTimeout: (task, ms) => { + const handle = setTimeout(task, ms); + // A countdown must never keep Pi's process alive. + handle.unref?.(); + return handle; + }, + clearTimeout: (handle) => clearTimeout(handle as NodeJS.Timeout), +}; + +export interface ExpiryListener { + /** The view changed: redraw. At most once per second while running. */ + change?(view: ExpiryView): void; + /** The limit lapsed. */ + expire?(): void; + /** The countdown was stopped before it lapsed. */ + stop?(reason: ExpiryStopReason): void; +} + +export interface ExpiryTimer { + /** The "question waiting" notification fired; the clock may now start. */ + arm(): void; + dispose(): void; + /** The form is on screen; starts the clock if it is armed. */ + hide(): void; + /** The user did something with the form. Stops the clock for good. */ + interact(): void; + /** Total limit, after the floor. */ + readonly seconds: number; + show(): void; + /** Stop for good, with a reason (e.g. the user opened the panel). */ + stop(reason: ExpiryStopReason): void; + subscribe(listener: ExpiryListener): () => void; + view(): ExpiryView; +} + +/** Shorter requests are raised to the floor, never rejected. */ +export function effectiveTimeoutSeconds( + requested: number | undefined, + minSeconds: number +): number | undefined { + if (requested === undefined) { + return; + } + return Math.max(Math.ceil(requested), Math.ceil(minSeconds)); +} + +export function createExpiryTimer( + seconds: number, + clock: ExpiryClock = systemClock +): ExpiryTimer { + const listeners = new Set(); + let phase: ExpiryPhase = "pending"; + let stopReason: ExpiryStopReason | undefined; + let armed = false; + let visible = false; + let deadline = 0; + let handle: unknown; + let disposed = false; + + const remaining = () => + phase === "running" + ? Math.max(0, Math.ceil((deadline - clock.now()) / 1000)) + : 0; + const view = (): ExpiryView => ({ + phase, + remainingSeconds: remaining(), + ...(stopReason ? { stopReason } : {}), + }); + const emit = (call: (listener: ExpiryListener) => void) => { + for (const listener of [...listeners]) { + call(listener); + } + }; + const cancelTick = () => { + if (handle !== undefined) { + clock.clearTimeout(handle); + handle = undefined; + } + }; + const schedule = () => { + // Wake at the next whole second, or at the deadline if that is sooner. + const left = deadline - clock.now(); + const toNextSecond = left - (Math.ceil(left / 1000) - 1) * 1000; + handle = clock.setTimeout(tick, Math.max(1, Math.min(left, toNextSecond))); + }; + function tick() { + handle = undefined; + if (phase !== "running") { + return; + } + if (clock.now() >= deadline) { + phase = "expired"; + emit((listener) => listener.change?.(view())); + emit((listener) => listener.expire?.()); + return; + } + emit((listener) => listener.change?.(view())); + schedule(); + } + function maybeStart() { + if (disposed || phase !== "pending" || !(armed && visible)) { + return; + } + phase = "running"; + deadline = clock.now() + seconds * 1000; + schedule(); + emit((listener) => listener.change?.(view())); + } + function stop(reason: ExpiryStopReason) { + if (phase !== "pending" && phase !== "running") { + return; + } + cancelTick(); + phase = "stopped"; + stopReason = reason; + emit((listener) => listener.stop?.(reason)); + emit((listener) => listener.change?.(view())); + } + + return { + seconds, + view, + subscribe(listener) { + listeners.add(listener); + return () => { + listeners.delete(listener); + }; + }, + arm() { + armed = true; + maybeStart(); + }, + show() { + visible = true; + maybeStart(); + }, + hide() { + visible = false; + if (phase === "running") { + stop("hidden"); + } + }, + interact() { + stop("interaction"); + }, + stop, + dispose() { + disposed = true; + cancelTick(); + listeners.clear(); + }, + }; +} + +/** + * The fallbacks that apply to `state` when its limit lapses: only questions + * that declared one, that still have no answer, and that were not skipped. + * Returns the answers to merge and the ids that received one. + */ +export function applyFallbacks(state: AskState): { + answers: AskState["answers"]; + applied: string[]; +} { + const answers = { ...state.answers }; + const applied: string[] = []; + for (const question of state.questions) { + if ( + !hasDeclaredFallback(question) || + isAnswerAnswered(answers[question.id]) || + state.skipped?.includes(question.id) + ) { + continue; + } + const index = question.options.findIndex( + (option) => option.value === question.fallback + ); + const option = question.options[index]; + if (!option) { + continue; + } + answers[question.id] = { + ...answers[question.id], + selected: [{ value: option.value, label: option.label, index: index + 1 }], + }; + applied.push(question.id); + } + return { answers, applied }; +} + +export function hasDeclaredFallback(question: AskQuestion): boolean { + return question.type !== "text" && !!question.fallback; +} + +/** The `expired` result for a form whose limit lapsed. */ +export function toExpiredResult(state: AskState): AskResult { + const { answers, applied } = applyFallbacks(state); + return { + ...toAskResult({ ...state, answers }, "expired"), + expired: applied, + }; +} + +/** + * Formats the countdown for the form header. `m:ss` under an hour so the + * remaining time reads at a glance. + */ +export function formatRemaining(totalSeconds: number): string { + const seconds = Math.max(0, Math.floor(totalSeconds)); + const hours = Math.floor(seconds / 3600); + const minutes = Math.floor((seconds % 3600) / 60); + const rest = String(seconds % 60).padStart(2, "0"); + return hours > 0 + ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}` + : `${minutes}:${rest}`; +} diff --git a/pi-ask/src/types.ts b/pi-ask/src/types.ts index 435cccd9..c378ec3b 100644 --- a/pi-ask/src/types.ts +++ b/pi-ask/src/types.ts @@ -118,9 +118,13 @@ export interface AskState { activeSubmitActionIndex: number; activeTabIndex: number; answers: Record; + /** Why the user cancelled, typed on the review tab. */ + cancelComment?: string; cancelled: boolean; completed: boolean; questions: AskQuestion[]; + /** Questions the user declined one by one; their answers were dropped. */ + skipped?: string[]; title?: string; view: ViewState; } diff --git a/pi-ask/tests/contract.test.ts b/pi-ask/tests/contract.test.ts index 746f58b9..ba4589f6 100644 --- a/pi-ask/tests/contract.test.ts +++ b/pi-ask/tests/contract.test.ts @@ -318,7 +318,9 @@ test("expired results name applied fallbacks and deny approval", () => { assert.ok(text.includes("DB: SQLite")); assert.ok(text.includes("Fallback applied for: DB.")); assert.ok(text.includes("not user approval")); - assert.ok(text.includes("keep irreversible actions blocked")); + assert.ok(text.includes("did not respond")); + assert.ok(text.includes("keep irreversible and risky actions blocked")); + assert.ok(text.includes("DB: SQLite [fallback")); const none = summarizeResult(receipt({ status: "expired", expired: [] })); assert.ok(none.includes("DB: (no answer)")); diff --git a/pi-ask/tests/expiry.test.ts b/pi-ask/tests/expiry.test.ts new file mode 100644 index 00000000..cb07cbb1 --- /dev/null +++ b/pi-ask/tests/expiry.test.ts @@ -0,0 +1,266 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createInitialState } from "../src/state/create.ts"; +import { + applyFallbacks, + createExpiryTimer, + effectiveTimeoutSeconds, + type ExpiryClock, + formatRemaining, + toExpiredResult, +} from "../src/state/expiry.ts"; +import type { AskParams } from "../src/types.ts"; + +/** A clock that moves only when told to; timers fire in order. */ +function fakeClock() { + let now = 1_000_000; + let next = 1; + const timers = new Map void }>(); + const clock: ExpiryClock = { + now: () => now, + setTimeout(task, ms) { + const id = next++; + timers.set(id, { at: now + ms, task }); + return id; + }, + clearTimeout(handle) { + timers.delete(handle as number); + }, + }; + return { + clock, + get pending() { + return timers.size; + }, + advance(ms: number) { + const end = now + ms; + for (;;) { + const due = [...timers.entries()] + .filter(([, timer]) => timer.at <= end) + .sort((a, b) => a[1].at - b[1].at)[0]; + if (!due) { + break; + } + timers.delete(due[0]); + now = Math.max(now, due[1].at); + due[1].task(); + } + now = end; + }, + }; +} + +function record(timer: ReturnType) { + const events: string[] = []; + timer.subscribe({ + change: (view) => + events.push(`change:${view.phase}:${view.remainingSeconds}`), + expire: () => events.push("expire"), + stop: (reason) => events.push(`stop:${reason}`), + }); + return events; +} + +test("the floor raises short limits and never rejects them", () => { + assert.equal(effectiveTimeoutSeconds(undefined, 30), undefined); + assert.equal(effectiveTimeoutSeconds(5, 30), 30); + assert.equal(effectiveTimeoutSeconds(90, 30), 90); + assert.equal(effectiveTimeoutSeconds(45.2, 30), 46); + assert.equal(effectiveTimeoutSeconds(1, 0.5), 1); +}); + +test("the clock does not start until the form is armed and visible", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + const events = record(timer); + + timer.show(); + assert.equal(timer.view().phase, "pending", "visible but not yet notified"); + assert.equal(fake.pending, 0, "no timer is scheduled while pending"); + fake.advance(120_000); + assert.deepEqual(events, []); + + timer.arm(); + assert.equal(timer.view().phase, "running"); + assert.equal(timer.view().remainingSeconds, 30); +}); + +test("a form that is queued or hidden never counts down", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + const events = record(timer); + timer.arm(); + fake.advance(10 * 60_000); + assert.equal(timer.view().phase, "pending"); + assert.deepEqual(events, []); + assert.equal(fake.pending, 0); + + timer.hide(); + assert.equal(timer.view().phase, "pending", "hiding an idle clock is a no-op"); + timer.show(); + assert.equal(timer.view().phase, "running"); +}); + +test("it ticks once per second and expires exactly at the limit", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(3, fake.clock); + const events = record(timer); + timer.arm(); + timer.show(); + fake.advance(1000); + fake.advance(1000); + fake.advance(1000); + assert.deepEqual(events, [ + "change:running:3", + "change:running:2", + "change:running:1", + "change:expired:0", + "expire", + ]); + assert.equal(fake.pending, 0, "nothing is left scheduled"); + fake.advance(60_000); + assert.equal(events.filter((event) => event === "expire").length, 1); +}); + +test("a late wake-up still expires and redraws only on a changed second", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(10, fake.clock); + const events = record(timer); + timer.arm(); + timer.show(); + fake.advance(250); + fake.advance(250); + assert.equal( + events.filter((event) => event.startsWith("change:running")).length, + 1, + "sub-second time does not redraw" + ); + fake.advance(60_000); + assert.equal(timer.view().phase, "expired"); +}); + +test("any interaction stops the clock for good", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + const events = record(timer); + timer.arm(); + timer.show(); + fake.advance(5000); + timer.interact(); + assert.equal(timer.view().phase, "stopped"); + assert.equal(timer.view().stopReason, "interaction"); + assert.equal(fake.pending, 0); + + // It cannot be restarted by showing, arming or waiting. + timer.hide(); + timer.show(); + timer.arm(); + fake.advance(10 * 60_000); + assert.equal(timer.view().phase, "stopped"); + assert.ok(!events.includes("expire")); + assert.equal(events.filter((event) => event.startsWith("stop:")).length, 1); +}); + +test("interacting before the clock started also stops it for good", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + timer.interact(); + timer.arm(); + timer.show(); + assert.equal(timer.view().phase, "stopped"); +}); + +test("hiding a running clock stops it for good", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + const events = record(timer); + timer.arm(); + timer.show(); + fake.advance(2000); + timer.hide(); + assert.equal(timer.view().stopReason, "hidden"); + timer.show(); + fake.advance(60_000); + assert.equal(timer.view().phase, "stopped"); + assert.ok(!events.includes("expire")); +}); + +test("dispose cancels the pending wake-up and silences listeners", () => { + const fake = fakeClock(); + const timer = createExpiryTimer(30, fake.clock); + const events = record(timer); + timer.arm(); + timer.show(); + assert.equal(fake.pending, 1); + timer.dispose(); + assert.equal(fake.pending, 0); + const seen = events.length; + fake.advance(60_000); + timer.show(); + assert.equal(events.length, seen); +}); + +test("remaining time reads as m:ss", () => { + assert.equal(formatRemaining(0), "0:00"); + assert.equal(formatRemaining(9), "0:09"); + assert.equal(formatRemaining(75), "1:15"); + assert.equal(formatRemaining(3725), "1:02:05"); +}); + +const PARAMS: AskParams = { + questions: [ + { + id: "db", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "lite", label: "SQLite" }, + ], + fallback: "lite", + }, + { + id: "cache", + prompt: "Which cache?", + options: [ + { value: "redis", label: "Redis" }, + { value: "none", label: "None" }, + ], + }, + { id: "notes", prompt: "Anything else?", type: "text" }, + ], +}; + +test("only declared fallbacks apply, and the rest stay unanswered", () => { + const result = toExpiredResult(createInitialState(PARAMS)); + assert.equal(result.status, "expired"); + assert.deepEqual(result.expired, ["db"]); + assert.deepEqual(Object.keys(result.answers), ["db"]); + assert.deepEqual(result.answers.db?.values, ["lite"]); + assert.deepEqual(result.answers.db?.labels, ["SQLite"]); + assert.deepEqual(result.unanswered, ["cache", "notes"]); +}); + +test("a question the user answered or skipped keeps no fallback", () => { + const state = createInitialState(PARAMS); + const answered = { + ...state, + answers: { + db: { selected: [{ value: "pg", label: "Postgres", index: 1 }] }, + }, + }; + assert.deepEqual(applyFallbacks(answered).applied, []); + assert.deepEqual( + applyFallbacks({ ...state, skipped: ["db"] }).applied, + [] + ); +}); + +test("an expiry with no declared fallback is still expired, with nothing applied", () => { + const state = createInitialState({ + questions: [{ id: "q", prompt: "Pick?", options: [{ value: "a", label: "A" }] }], + }); + const result = toExpiredResult(state); + assert.equal(result.status, "expired"); + assert.deepEqual(result.expired, []); + assert.deepEqual(result.answers, {}); +}); From 189c6948b79c415e11af145f430fe10e826e38d0 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 00:59:15 +0000 Subject: [PATCH 14/38] feat(ask): journal countdown stops and corrections to expired forms Adds expiry and dismiss entries, a supersedes link on outcomes, an offer window for reopening expired forms, and delivery text for timed-out forms and late corrections. --- pi-ask/src/delivery.ts | 56 +++++++++++++++++++------ pi-ask/src/i18n.ts | 24 +++++++++++ pi-ask/src/journal/entries.ts | 36 +++++++++++++++- pi-ask/src/journal/journal.ts | 17 +++++++- pi-ask/src/journal/replay.ts | 39 +++++++++++++++-- pi-ask/tests/journal-replay.test.ts | 65 +++++++++++++++++++++++++++++ pi-ask/tests/outbox.test.ts | 26 ++++++++++++ 7 files changed, 243 insertions(+), 20 deletions(-) diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 9482e519..0fe837ce 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -64,21 +64,45 @@ export interface AskDelivery { } /** Model-facing text of the follow-up message. */ -export function formatDeliveredOutcome(result: AskResult): string { +export function formatDeliveredOutcome( + result: AskResult, + options: { correction?: boolean } = {} +): string { const requestId = result.requestId ?? ""; + const strings = askStrings(); const cancelled = result.status === "cancelled"; - const heading = cancelled - ? askStrings().cancelDelivered(requestId, result.title) - : askStrings().answerDelivered(requestId, result.title); + const expired = result.status === "expired"; + let heading = strings.answerDelivered(requestId, result.title); + if (options.correction) { + heading = cancelled + ? strings.correctionCancelDelivered(requestId, result.title) + : strings.correctionDelivered(requestId, result.title); + } else if (cancelled) { + heading = strings.cancelDelivered(requestId, result.title); + } else if (expired) { + heading = strings.expiredDelivered(requestId, result.title); + } + const fallbacks = new Set(result.expired ?? []); // Each question is named by id and prompt: the call that asked may be // far back in the context, or compacted away. const lines = result.questions.map((question) => { const asked = `- ${question.id} "${oneLine(question.prompt)}"`; - return cancelled - ? asked - : `${asked}: ${formatAnswer(result.answers[question.id])}`; + if (cancelled) { + return asked; + } + const answer = formatAnswer(result.answers[question.id]); + return `${asked}: ${answer}${fallbacks.has(question.id) ? ` ${strings.fallbackMark}` : ""}`; }); - return [heading, ...lines].join("\n"); + const trailer = expired + ? [ + strings.expiredSummary( + result.questions + .filter((question) => fallbacks.has(question.id)) + .map((question) => question.label) + ), + ] + : []; + return [heading, ...lines, ...trailer].join("\n"); } function formatAnswer(answer: AskResultAnswer | undefined): string { @@ -105,14 +129,16 @@ function oneLine(text: string): string { } function answerMessage(outcome: AskOutcomeEntry) { + const correction = !!outcome.supersedes; const details: AskAnswerMessageDetails = { + ...(correction ? { correction } : {}), requestId: outcome.requestId, outcomeId: outcome.outcomeId, result: outcome.result, }; return { customType: ASK_ANSWER_MESSAGE_TYPE, - content: formatDeliveredOutcome(outcome.result), + content: formatDeliveredOutcome(outcome.result, { correction }), display: true, details, }; @@ -230,10 +256,14 @@ export function renderAskAnswerMessage( return; } const strings = askStrings(); - const label = - result.status === "cancelled" - ? strings.cancelledCardLabel - : strings.answeredCardLabel; + let label = strings.answeredCardLabel; + if (details?.correction) { + label = strings.correctedCardLabel; + } else if (result.status === "cancelled") { + label = strings.cancelledCardLabel; + } else if (result.status === "expired") { + label = strings.expiredCardLabel; + } const subject = result.title ?? result.requestId ?? details?.requestId ?? ""; const heading = theme.fg("toolTitle", theme.bold("ask_user ")) + diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index 8785156b..7103ef8d 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -41,6 +41,12 @@ export interface AskStrings { answerDelivered: (requestId: string, title?: string) => string; /** Follow-up message for a form cancelled after its tool call ended. */ cancelDelivered: (requestId: string, title?: string) => string; + /** Heading of the follow-up message for a form that timed out while queued. */ + expiredDelivered: (requestId: string, title?: string) => string; + /** Heading when the user answers a form that had timed out (late override). */ + correctionDelivered: (requestId: string, title?: string) => string; + /** Heading when the user cancels a form that had timed out. */ + correctionCancelDelivered: (requestId: string, title?: string) => string; /** Shown to the user when an interrupted form reopens. */ recoveredNotice: string; /** Line under the editor while forms wait in the queue. */ @@ -61,6 +67,8 @@ export interface AskStrings { /** Transcript card headings for a delivered answer or cancellation. */ answeredCardLabel: string; cancelledCardLabel: string; + correctedCardLabel: string; + expiredCardLabel: string; /** Short transcript labels for the non-answer statuses. */ queuedLabel: string; deferredLabel: string; @@ -112,6 +120,12 @@ const EN_STRINGS: AskStrings = { `User answered your earlier ask_user form ${formRef(requestId, title)}:`, cancelDelivered: (requestId, title) => `User cancelled your earlier ask_user form ${formRef(requestId, title)}. Cancellation is not approval; keep risky actions blocked.`, + expiredDelivered: (requestId, title) => + `Your earlier ask_user form ${formRef(requestId, title)} timed out.`, + correctionDelivered: (requestId, title) => + `CORRECTION: the user answered your earlier ask_user form ${formRef(requestId, title)} after it timed out. This replaces the timed-out result, fallbacks included. A question marked (no answer) has none: do not rely on a fallback for it.`, + correctionCancelDelivered: (requestId, title) => + `CORRECTION: the user cancelled your earlier ask_user form ${formRef(requestId, title)} after it timed out. Any fallback you applied is withdrawn. Cancellation is not approval; keep risky actions blocked.`, recoveredNotice: "Reopened a question left unanswered when Pi last stopped", pendingIndicator: ({ focused, forms, key, questions }) => [ @@ -130,6 +144,8 @@ const EN_STRINGS: AskStrings = { "This Pi version cannot focus the question panel; update Pi to answer queued questions", answeredCardLabel: "answered", cancelledCardLabel: "cancelled", + correctedCardLabel: "corrected", + expiredCardLabel: "timed out", queuedLabel: "Queued", deferredLabel: "Answer later", expiredLabel: "Expired", @@ -167,6 +183,12 @@ const ZH_STRINGS: AskStrings = { `用户回答了你之前的 ask_user 表单 ${formRef(requestId, title)}:`, cancelDelivered: (requestId, title) => `用户取消了你之前的 ask_user 表单 ${formRef(requestId, title)}。取消不代表批准;有风险的操作仍须保持阻止。`, + expiredDelivered: (requestId, title) => + `你之前的 ask_user 表单 ${formRef(requestId, title)} 已超时。`, + correctionDelivered: (requestId, title) => + `更正:用户在你之前的 ask_user 表单 ${formRef(requestId, title)} 超时后作出了回答。此回答取代超时结果(包括备选项)。标为(无回答)的问题没有回答,不要依赖其备选项。`, + correctionCancelDelivered: (requestId, title) => + `更正:用户在你之前的 ask_user 表单 ${formRef(requestId, title)} 超时后取消了它。你应用过的备选项一律撤回。取消不代表批准;有风险的操作仍须保持阻止。`, recoveredNotice: "已重新打开上次 Pi 停止时未回答的问题", pendingIndicator: ({ focused, forms, key, questions }) => [ @@ -184,6 +206,8 @@ const ZH_STRINGS: AskStrings = { panelFocusUnsupported: "当前 Pi 版本无法聚焦问题面板;请更新 Pi 以回答排队的问题", answeredCardLabel: "已回答", cancelledCardLabel: "已取消", + correctedCardLabel: "已更正", + expiredCardLabel: "已超时", queuedLabel: "已排队", deferredLabel: "稍后回答", expiredLabel: "已超时", diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts index 5717c988..6c28f7cd 100644 --- a/pi-ask/src/journal/entries.ts +++ b/pi-ask/src/journal/entries.ts @@ -82,6 +82,8 @@ export interface AskOutcomeEntry extends AskJournalEntryBase { kind: "outcome"; outcomeId: string; result: AskResult; + /** The expired outcome this one corrects (late override). */ + supersedes?: string; } /** @@ -102,16 +104,40 @@ export interface AskPanelEntry extends AskJournalEntryBase { kind: "panel"; } +/** Why a form's countdown will never fire; see `state/expiry.ts`. */ +export type AskExpiryStopReason = "interaction" | "hidden"; + +/** + * The form's countdown was stopped by the user. It is never restarted: a + * reload, resume or fork must not give a form back a clock the user stopped. + */ +export interface AskExpiryEntry extends AskJournalEntryBase { + kind: "expiry"; + reason: AskExpiryStopReason; +} + +/** + * The user closed an expired form without correcting it. It is no longer + * offered for a late override; the agent's earlier result stands. + */ +export interface AskDismissEntry extends AskJournalEntryBase { + kind: "dismiss"; +} + export type AskJournalEntry = | AskFormEntry | AskDraftEntry | AskDeferEntry | AskOutcomeEntry | AskDeliveredEntry - | AskPanelEntry; + | AskPanelEntry + | AskExpiryEntry + | AskDismissEntry; /** `details` of the follow-up message; also proves delivery on replay. */ export interface AskAnswerMessageDetails { + /** The message corrects an earlier expired result. */ + correction?: boolean; outcomeId: string; requestId: string; result: AskResult; @@ -124,6 +150,8 @@ const ENTRY_KINDS = new Set([ "outcome", "delivered", "panel", + "expiry", + "dismiss", ]); /** Journal data from a session entry, or undefined if it is not usable. */ @@ -160,6 +188,12 @@ export function parseJournalEntry(data: unknown): AskJournalEntry | undefined { return typeof data.hidden === "boolean" ? (data as unknown as AskPanelEntry) : undefined; + case "expiry": + return data.reason === "interaction" || data.reason === "hidden" + ? (data as unknown as AskExpiryEntry) + : undefined; + case "dismiss": + return data as unknown as AskDismissEntry; default: return data as unknown as AskDeferEntry; } diff --git a/pi-ask/src/journal/journal.ts b/pi-ask/src/journal/journal.ts index 24893f7a..00773c7c 100644 --- a/pi-ask/src/journal/journal.ts +++ b/pi-ask/src/journal/journal.ts @@ -13,6 +13,7 @@ import { ASK_JOURNAL_ENTRY_TYPE, ASK_JOURNAL_VERSION, type AskDraftSnapshot, + type AskExpiryStopReason, type AskFormMode, type AskFormSnapshot, type AskJournalEntry, @@ -38,6 +39,10 @@ export interface AskJournal { recordDelivered(requestId: string, outcomeId: string): void; /** A foreground form moved to the queue ("answer later"). */ recordDefer(requestId: string): void; + /** The user closed an expired form without correcting it. */ + recordDismiss(requestId: string): void; + /** The user stopped a form's countdown. It never restarts. */ + recordExpiryStop(requestId: string, reason: AskExpiryStopReason): void; /** The user hid or reopened the panel; `requestId` is the form shown. */ recordPanel(hidden: boolean, requestId?: string): void; /** Saves an accepted form and returns its new request id. */ @@ -53,7 +58,8 @@ export interface AskJournal { recordOutcome( requestId: string, result: AskResult, - channel: AskOutcomeChannel + channel: AskOutcomeChannel, + supersedes?: string ): AskOutcomeEntry; } @@ -111,15 +117,22 @@ export function createAskJournal( recordPanel(hidden, requestId = "") { write({ kind: "panel", requestId, hidden }); }, - recordOutcome(requestId, result, channel) { + recordOutcome(requestId, result, channel, supersedes) { return write({ kind: "outcome", requestId, outcomeId: newId(), channel, result: { ...result, requestId }, + ...(supersedes ? { supersedes } : {}), }) as AskOutcomeEntry; }, + recordDismiss(requestId) { + write({ kind: "dismiss", requestId }); + }, + recordExpiryStop(requestId, reason) { + write({ kind: "expiry", requestId, reason }); + }, recordDelivered(requestId, outcomeId) { write({ kind: "delivered", requestId, outcomeId }); }, diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts index 2ce5d377..d27aa130 100644 --- a/pi-ask/src/journal/replay.ts +++ b/pi-ask/src/journal/replay.ts @@ -27,11 +27,15 @@ export interface AskJournalRecord { createdAt: number; /** A foreground form the user sent to the queue with "answer later". */ deferred: boolean; + /** The user stopped this form's countdown; it never runs again. */ + clockStopped: boolean; /** Outcome ids that already reached the agent as a follow-up message. */ delivered: ReadonlySet; draft?: AskDraftSnapshot; form: AskFormSnapshot; mode: AskFormMode; + /** The user closed an expired form without correcting it. */ + offerDismissed: boolean; /** Latest outcome; undefined while the form is still open. */ outcome?: AskOutcomeEntry; requestId: string; @@ -97,6 +101,8 @@ export function replayJournal( form: journalEntry.form, toolCallId: journalEntry.toolCallId, deferred: false, + clockStopped: false, + offerDismissed: false, delivered: new Set(), supersededByMessage: false, }); @@ -117,6 +123,14 @@ export function replayJournal( break; case "outcome": record.outcome = journalEntry; + // A new outcome is a new life: an earlier dismissal does not carry. + record.offerDismissed = false; + break; + case "expiry": + record.clockStopped = true; + break; + case "dismiss": + record.offerDismissed = true; break; case "delivered": deliveredOutcomeIds.set(journalEntry.outcomeId, journalEntry.requestId); @@ -173,20 +187,37 @@ export function queuedForms(state: AskJournalState): AskJournalRecord[] { */ export function pendingForms( state: AskJournalState, - live: ReadonlySet = new Set() + live: ReadonlySet = new Set(), + reopened: ReadonlySet = new Set() ): AskJournalRecord[] { const waiting = new Set( [...queuedForms(state), ...interruptedForms(state)] .filter((record) => record.deferred || !live.has(record.requestId)) .map((record) => record.requestId) ); + // An expired form joins the queue only once the user asked for it. + for (const record of reopenableForms(state)) { + if (reopened.has(record.requestId)) { + waiting.add(record.requestId); + } + } return state.records.filter((record) => waiting.has(record.requestId)); } -/** Expired forms: resolved by fallback, still open to a late correction. */ -export function reopenableForms(state: AskJournalState): AskJournalRecord[] { +/** + * Expired forms: resolved by fallback, still open to a late correction. They + * are offered until the user corrects or dismisses them, or `offer` runs out + * (`maxAgeMs` after the expiry, as stamped on the outcome). + */ +export function reopenableForms( + state: AskJournalState, + offer?: { maxAgeMs: number; now: number } +): AskJournalRecord[] { return state.records.filter( - (record) => record.outcome?.result.status === "expired" + (record) => + record.outcome?.result.status === "expired" && + !record.offerDismissed && + (!offer || offer.now - record.outcome.at <= offer.maxAgeMs) ); } diff --git a/pi-ask/tests/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts index e6831fb0..374be54b 100644 --- a/pi-ask/tests/journal-replay.test.ts +++ b/pi-ask/tests/journal-replay.test.ts @@ -290,3 +290,68 @@ test("panel visibility follows the latest panel entry on the branch", () => { }; assert.equal(replayJournal([...b.entries, malformed]).panelHidden, false); }); + +test("an expired form joins the queue only when the user reopened it", () => { + const b = branch(); + const requestId = b.form("background"); + b.journal.recordOutcome(requestId, result("expired"), "message"); + const state = replayJournal(b.entries); + assert.deepEqual(pendingForms(state), []); + assert.deepEqual( + pendingForms(state, new Set(), new Set([requestId])).map( + (record) => record.requestId + ), + [requestId] + ); +}); + +test("a dismissed or stale expired form is no longer offered", () => { + const b = branch(); + const dismissed = b.form("background"); + const stale = b.form("background"); + const fresh = b.form("background"); + b.journal.recordOutcome(dismissed, result("expired"), "message"); + b.journal.recordOutcome(stale, result("expired"), "message"); + const staleAt = b.entries.length; + for (let index = 0; index < 5000; index++) { + b.message("user"); + } + b.journal.recordOutcome(fresh, result("expired"), "message"); + b.journal.recordDismiss(dismissed); + const state = replayJournal(b.entries); + const offered = (now: number, maxAgeMs: number) => + reopenableForms(state, { now, maxAgeMs }).map((record) => record.requestId); + const freshAt = 1000 + b.entries.length - 2; + assert.ok(staleAt < freshAt); + assert.deepEqual(offered(freshAt + 1, 3000), [fresh]); + assert.deepEqual(offered(freshAt + 1, 10_000), [stale, fresh]); + assert.deepEqual( + reopenableForms(state).map((record) => record.requestId), + [stale, fresh], + "without an offer window only dismissal ends it" + ); +}); + +test("a correction names the outcome it supersedes and ends the offer", () => { + const b = branch(); + const requestId = b.form("background"); + const expired = b.journal.recordOutcome(requestId, result("expired"), "message"); + const correction = b.journal.recordOutcome( + requestId, + result(), + "message", + expired.outcomeId + ); + const state = replayJournal(b.entries); + assert.equal(getRecord(state, requestId)?.outcome?.supersedes, expired.outcomeId); + assert.equal(correction.supersedes, expired.outcomeId); + assert.deepEqual(reopenableForms(state), []); +}); + +test("a stopped countdown is remembered across a rebuild", () => { + const b = branch(); + const requestId = b.form("background"); + assert.equal(getRecord(replayJournal(b.entries), requestId)?.clockStopped, false); + b.journal.recordExpiryStop(requestId, "interaction"); + assert.equal(getRecord(replayJournal(b.entries), requestId)?.clockStopped, true); +}); diff --git a/pi-ask/tests/outbox.test.ts b/pi-ask/tests/outbox.test.ts index 182338e1..547d752b 100644 --- a/pi-ask/tests/outbox.test.ts +++ b/pi-ask/tests/outbox.test.ts @@ -134,3 +134,29 @@ test("a delivered cancellation lists what was asked and none of the draft", () = ); assert.doesNotMatch(text, /Postgres|boring/); }); + +test("a form that timed out is delivered with its fallbacks marked and denied as approval", () => { + const text = formatDeliveredOutcome({ + ...RESULT, + status: "expired", + expired: ["db"], + answers: { db: { values: ["pg"], labels: ["Postgres"] } }, + }); + assert.match(text, /^Your earlier ask_user form ask-1 \(Storage\) timed out\./); + assert.match(text, /- db "Which database\?": Postgres \[pg\] \[fallback: not chosen by the user\]/); + assert.match(text, /did not respond/); + assert.match(text, /not user approval; keep irreversible and risky actions blocked/); +}); + +test("a late correction says it replaces the timed-out result", () => { + const answered = formatDeliveredOutcome(RESULT, { correction: true }); + assert.match(answered, /^CORRECTION: the user answered your earlier ask_user form ask-1 \(Storage\) after it timed out/); + assert.match(answered, /replaces the timed-out result, fallbacks included/); + assert.match(answered, /\(no answer\)/); + const cancelled = formatDeliveredOutcome( + { ...RESULT, status: "cancelled" }, + { correction: true } + ); + assert.match(cancelled, /^CORRECTION: the user cancelled/); + assert.match(cancelled, /fallback you applied is withdrawn/); +}); From 9e01324f1f6127a81fccbb7b30bb8e79a9ebb85d Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 01:06:42 +0000 Subject: [PATCH 15/38] feat(ask): count down visible forms and apply declared fallbacks timeoutSeconds and fallback ship in the schema when expiry is on. The clock starts when a form is on screen and notified, stops for good on any key, hide or takeover, and never runs for a form recovered after a restart. An expired background form wakes an idle agent; an expired form can be reopened for one late correction. /ask-settings toggles expiry and shows the floor. --- pi-ask/src/ask-tool.ts | 53 ++- pi-ask/src/background.ts | 165 ++++++++- pi-ask/src/features.ts | 2 +- pi-ask/src/i18n.ts | 29 ++ pi-ask/src/runtime.ts | 12 +- pi-ask/src/ui/controller.ts | 51 ++- pi-ask/src/ui/panel.ts | 6 + pi-ask/src/ui/render-frame.ts | 9 +- pi-ask/src/ui/render-question.ts | 4 +- pi-ask/src/ui/render-types.ts | 2 + pi-ask/src/ui/render.ts | 41 ++- pi-ask/src/ui/settings-list.ts | 80 +++-- pi-ask/src/ui/view-models/question.ts | 6 + pi-ask/tests/expiry-flow.test.ts | 473 ++++++++++++++++++++++++++ pi-ask/tests/expiry.test.ts | 41 +-- pi-ask/tests/settings-list.test.ts | 30 ++ pi-ask/tests/support/fake-clock.ts | 41 +++ pi-ask/tests/token-ceiling.test.ts | 9 +- scripts/packages.mjs | 2 +- 19 files changed, 966 insertions(+), 90 deletions(-) create mode 100644 pi-ask/tests/expiry-flow.test.ts create mode 100644 pi-ask/tests/support/fake-clock.ts diff --git a/pi-ask/src/ask-tool.ts b/pi-ask/src/ask-tool.ts index 62d4b749..2839d38d 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -12,10 +12,15 @@ import { successfulResponse, validateParams, } from "./ask-tool-helpers.ts"; +import { getAskConfigStore } from "./config/store.ts"; import { type AskFeatures, NO_ASK_FEATURES } from "./features.ts"; import { buildAskParamsSchema, stripSchemaDescriptions } from "./schema.ts"; import { toFormSnapshot } from "./journal/journal.ts"; import { type AskRuntime, createAskRuntime } from "./runtime.ts"; +import { + createExpiryTimer, + effectiveTimeoutSeconds, +} from "./state/expiry.ts"; import { prepareAskParams } from "./state/normalize.ts"; import { toAskResult } from "./state/result.ts"; import type { AskParams, AskResult, AskState } from "./types.ts"; @@ -57,7 +62,7 @@ export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) } async function executeAskTool( - { background, journal, live }: AskRuntime, + { background, clock, journal, live }: AskRuntime, features: AskFeatures, toolCallId: string, params: AskParams, @@ -68,10 +73,18 @@ async function executeAskTool( if (!validation.ok) { return invalidPayloadResponse(params, validation.issues); } - const form = toFormSnapshot(validation.state, params.timeoutSeconds); + // A limit counts only where there is a screen to count down on, and only + // while expiry is on both at registration and in the live config. A stale + // call that still carries one after expiry was switched off just waits. + const expirySeconds = + ctx.mode === "tui" && features.expiry + ? await resolveExpirySeconds(params.timeoutSeconds) + : undefined; + const form = toFormSnapshot(validation.state, expirySeconds); if (ctx.mode !== "tui") { // No persistent panel here, so `background` blocks like any other call. + // The same goes for `timeoutSeconds`: there is no countdown, the call waits. // Hosts with dialog UI but no custom TUI (RPC subagents, ACP clients) // get the card-based fallback; print/json keeps the pending summary. const requestId = journal.recordForm({ mode: "foreground", form, toolCallId }); @@ -93,7 +106,9 @@ async function executeAskTool( // Journalled first: the receipt promises an answer that survives a // restart. No outcome is written; a receipt is not one. const requestId = journal.recordForm({ mode: "background", form, toolCallId }); - const pending = background.enqueue(ctx, requestId, "background"); + const pending = background.enqueue(ctx, requestId, "background", { + timeoutSeconds: expirySeconds, + }); return successfulResponse({ ...receipt(validation.state, "queued", requestId), pending, @@ -103,9 +118,18 @@ async function executeAskTool( // Journalled before any waiting, so a form that never returns can be // recovered; the outcome is journalled before the tool returns. const requestId = journal.recordForm({ mode: "foreground", form, toolCallId }); + const timer = + expirySeconds === undefined + ? undefined + : createExpiryTimer(expirySeconds, clock); + // A stopped countdown is journalled, so no rebuild can bring it back. + timer?.subscribe({ + stop: (reason) => journal.recordExpiryStop(requestId, reason), + }); const openForm = () => runAskFlow(ctx, params, { allowDefer: !!background, + expiry: timer && { owned: true, timer }, onStateChange: journal.draftRecorder(requestId), }); let result: AskResult; @@ -117,6 +141,7 @@ async function executeAskTool( ? background.foreground(ctx, openForm) : openForm()); } finally { + timer?.dispose(); live.delete(requestId); ctx.ui.setWorkingVisible(true); } @@ -127,9 +152,12 @@ async function executeAskTool( background.enqueue(ctx, requestId, "deferred"); return successfulResponse(receipt(validation.state, "deferred", requestId)); } - return successfulResponse( - journal.recordOutcome(requestId, result, "tool").result - ); + const outcome = journal.recordOutcome(requestId, result, "tool"); + if (result.status === "expired") { + // It can now be reopened for a late correction. + background?.formEnded(ctx); + } + return successfulResponse(outcome.result); } /** A receipt names the form and carries no answers, not even drafted ones. */ @@ -140,3 +168,16 @@ function receipt( ): AskResult { return { ...toAskResult(state, status), requestId }; } + +/** The call's limit after the floor, or undefined when expiry is off. */ +async function resolveExpirySeconds( + requested: number | undefined +): Promise { + if (requested === undefined) { + return; + } + const { config } = await getAskConfigStore().ensureLoaded(); + return config.expiry.enabled + ? effectiveTimeoutSeconds(requested, config.expiry.minSeconds) + : undefined; +} diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 7b923583..45e23bb1 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -35,10 +35,16 @@ import { getRecord, isOpen, pendingForms, + reopenableForms, } from "./journal/replay.ts"; import type { AskRuntime } from "./runtime.ts"; import { createInitialState } from "./state/create.ts"; import { applyDraftSnapshot } from "./state/draft.ts"; +import { + createExpiryTimer, + type ExpiryTimer, + toExpiredResult, +} from "./state/expiry.ts"; import { type AskPanelEvent, EMPTY_PANEL, @@ -52,9 +58,20 @@ import { type AskPanel, createAskPanel } from "./ui/panel.ts"; export const ASK_PENDING_WIDGET_KEY = "pi-ask:pending"; +/** + * How long an expired form is offered for a late correction: it shows in the + * pending indicator and `/ask-panel`, measured from the expiry. After that + * the agent's result stands and nothing nags. + */ +export const EXPIRED_OFFER_MS = 60 * 60 * 1000; + export interface AskBackgroundDeps { /** Runs `task` after the current lifecycle dispatch has finished. */ defer?: (task: () => void) => void; + /** Clock for the countdown of queued forms; tests inject their own. */ + newTimer?: (seconds: number) => ExpiryTimer; + /** Epoch milliseconds; used for the late-override offer window. */ + now?: () => number; } export interface AskBackground { @@ -74,13 +91,19 @@ export interface AskBackground { enqueue( ctx: ExtensionContext, requestId: string, - origin: "background" | "deferred" + origin: "background" | "deferred", + options?: { timeoutSeconds?: number } ): number; /** * Runs a blocking form. It owns the keyboard: the panel is off screen * until `run` settles, then returns with the focus it had. */ foreground(ctx: ExtensionContext, run: () => Promise): Promise; + /** + * A blocking form just got its outcome (e.g. it expired): refresh the + * queue and the late-override offer. + */ + formEnded(ctx: ExtensionContext): void; /** Pi may have become idle without a run settling: deliver if so. */ poke(ctx: ExtensionContext): void; /** `/ask-panel`: show the panel and give it the keyboard. */ @@ -124,12 +147,22 @@ export function registerAskBackground( export function createAskBackground( pi: Pick, - { journal, live }: AskRuntime, + { clock, journal, live }: AskRuntime, deps: AskBackgroundDeps = {} ): AskBackground { const defer = deps.defer ?? ((task) => setTimeout(task, 0)); + const now = deps.now ?? clock?.now ?? Date.now; + const newTimer = + deps.newTimer ?? ((seconds) => createExpiryTimer(seconds, clock)); const delivery = createAskDelivery(pi); const recorders = new Map void>(); + // Countdowns of background forms created in THIS process. A form from an + // earlier process (restart, resume, fork, reload) never has one: the user + // had no fair chance to see its clock, so it waits like a normal form. + const timers = new Map(); + // Expired forms the user asked to reopen, and those still on offer. + const reopened = new Set(); + let offers: string[] = []; // Recovered forms announced in this process. const announced = new Set(); let state = EMPTY_PANEL; @@ -191,19 +224,68 @@ export function createAskBackground( function readQueue(current: ExtensionContext) { const journalState = readAskJournal(current); - const pending = pendingForms(journalState, live); + const pending = pendingForms(journalState, live, reopened); records = new Map(pending.map((record) => [record.requestId, record])); for (const requestId of recorders.keys()) { if (!records.has(requestId)) { recorders.delete(requestId); } } + for (const requestId of [...reopened]) { + if (!records.has(requestId)) { + reopened.delete(requestId); + } + } + for (const [requestId, timer] of [...timers]) { + // Gone from this branch: nothing is left to count down. + if (!records.has(requestId)) { + releaseTimer(requestId, timer); + } + } + offers = reopenableForms(journalState, { + now: now(), + maxAgeMs: EXPIRED_OFFER_MS, + }) + .map((record) => record.requestId) + .filter((requestId) => !reopened.has(requestId)); return { queue: pending.map((record) => record.requestId), hidden: journalState.panelHidden, }; } + function releaseTimer(requestId: string, timer = timers.get(requestId)) { + timer?.dispose(); + timers.delete(requestId); + } + + /** A form counts down only while it is the one on screen. */ + function syncTimers() { + const view = panelView(state); + for (const [requestId, timer] of timers) { + if (view.visible && view.formId === requestId) { + timer.show(); + } else { + timer.hide(); + } + } + } + + /** The limit lapsed with the form still on screen, untouched. */ + function expire(requestId: string) { + const record = records.get(requestId); + if (!(record && isQueued(requestId))) { + return; + } + const formState = + panel.state(requestId) ?? + applyDraftSnapshot( + createInitialState(formToParams(record.form)), + record.draft + ); + complete(requestId, toExpiredResult(formState)); + } + function dispatch(event: AskPanelEvent) { state = reducePanel(state, event); render(); @@ -231,6 +313,7 @@ export function createAskBackground( try { panel.retain(state.queue); const focusedOk = panel.apply(ctx, panelView(state), loadForm); + syncTimers(); if (!focusedOk) { state = reducePanel(state, { type: "blurred" }); if (!focusWarned) { @@ -257,11 +340,14 @@ export function createAskBackground( announced.add(requestId); ctx.ui.notify(askStrings().recoveredNotice, "info"); } + const expired = record.outcome?.result.status === "expired"; return { requestId, config, draft: record.draft, params: formToParams(record.form), + expiry: timers.get(requestId), + ...(expired ? { banner: askStrings().lateOverrideBanner } : {}), }; } @@ -270,7 +356,7 @@ export function createAskBackground( return; } const forms = state.queue.length; - const text = + const lines = [ forms === 0 ? undefined : askStrings().pendingIndicator({ @@ -281,14 +367,21 @@ export function createAskBackground( ), key: getGlobalBindings(config).panelFocus.label, focused: panelView(state).focused, - }); + }), + offers.length === 0 + ? undefined + : askStrings().expiredIndicator(offers.length), + ].filter((line): line is string => line !== undefined); + const text = lines.length === 0 ? undefined : lines.join("\n"); if (text === indicator) { return; } indicator = text; ctx.ui.setWidget( ASK_PENDING_WIDGET_KEY, - text === undefined ? undefined : [ctx.ui.theme.fg("dim", text)], + text === undefined + ? undefined + : lines.map((line) => ctx?.ui.theme.fg("dim", line) ?? line), { placement: "belowEditor" } ); } @@ -317,19 +410,37 @@ export function createAskBackground( // The journal, not memory, says whether this branch still waits for // this form: a form from another branch writes nothing here. const record = getRecord(readAskJournal(current), requestId); + // A reopened expired form is open to one correction. + const expiredOutcome = + record && reopened.has(requestId) && !record.offerDismissed + ? record.outcome + : undefined; + const correcting = expiredOutcome?.result.status === "expired"; if ( record && - isOpen(record) && + (isOpen(record) || correcting) && isQueued(requestId) && result.status !== "unavailable" ) { - journal.recordOutcome(requestId, result, "message"); - delivery.post(); - delivery.pump(current); + if (correcting && result.status === "cancelled" && !result.comment) { + // Closing it without a word leaves the agent's result as it is. + journal.recordDismiss(requestId); + } else { + journal.recordOutcome( + requestId, + result, + "message", + correcting ? expiredOutcome?.outcomeId : undefined + ); + delivery.post(); + delivery.pump(current); + } } } catch { // A stale context: nothing is written. } + releaseTimer(requestId); + reopened.delete(requestId); refresh((queue) => ({ type: "removed", queue })); } @@ -353,7 +464,16 @@ export function createAskBackground( }); } + /** The user opened or focused the panel on purpose: they are here. */ + function userEngaged() { + const head = state.queue[0]; + if (head !== undefined) { + timers.get(head)?.stop("interaction"); + } + } + function toggleFocus() { + userEngaged(); if (state.hidden) { journal.recordPanel(false, state.queue[0]); } @@ -411,10 +531,23 @@ export function createAskBackground( poke(next); }, poke, - enqueue(next, requestId, origin) { + formEnded(next) { + if (adopt(next)) { + refresh((queue) => ({ type: "removed", queue })); + } + }, + enqueue(next, requestId, origin, options = {}) { if (!adopt(next)) { return 0; } + if (origin === "background" && options.timeoutSeconds !== undefined) { + const timer = newTimer(options.timeoutSeconds); + timer.subscribe({ + stop: (reason) => journal.recordExpiryStop(requestId, reason), + expire: () => expire(requestId), + }); + timers.set(requestId, timer); + } if (origin === "deferred") { // "Later" means the keyboard goes back to the input. state = reducePanel(state, { type: "blurred" }); @@ -445,11 +578,18 @@ export function createAskBackground( next.ui.notify(askStrings().panelNeedsTui, "error"); return; } + // Timed-out forms the agent has already moved past come back here, + // on request only. Read the branch first: the offers may be new. + refresh((queue) => ({ type: "removed", queue })); + for (const requestId of offers) { + reopened.add(requestId); + } refresh((queue) => ({ type: "removed", queue })); if (state.queue.length === 0) { next.ui.notify(askStrings().nothingPending, "info"); return; } + userEngaged(); if (state.hidden) { journal.recordPanel(false, state.queue[0]); } @@ -486,6 +626,9 @@ export function createAskBackground( // The UI is already gone. } disposed = true; + for (const [requestId, timer] of [...timers]) { + releaseTimer(requestId, timer); + } ctx = undefined; unbindInput?.(); unsubscribeConfig(); diff --git a/pi-ask/src/features.ts b/pi-ask/src/features.ts index be54a6f9..c0b5db57 100644 --- a/pi-ask/src/features.ts +++ b/pi-ask/src/features.ts @@ -24,7 +24,7 @@ export const ALL_ASK_FEATURES: AskFeatures = { */ export const SHIPPED_ASK_FEATURES: AskFeatures = { background: true, - expiry: false, + expiry: true, }; /** Read once at registration, so a config change applies on reload only. */ diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index 7103ef8d..ca47307b 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -47,6 +47,16 @@ export interface AskStrings { correctionDelivered: (requestId: string, title?: string) => string; /** Heading when the user cancels a form that had timed out. */ correctionCancelDelivered: (requestId: string, title?: string) => string; + /** Form header while the limit counts down. */ + countdownRunning: (remaining: string, hasFallback: boolean) => string; + /** Form header after the user stopped the countdown. */ + countdownStopped: string; + /** Marks the option the agent declared as its fallback. */ + fallbackOptionMarker: string; + /** Form header when an expired form is reopened for a correction. */ + lateOverrideBanner: string; + /** Under the editor: expired forms that can still be answered. */ + expiredIndicator: (count: number) => string; /** Shown to the user when an interrupted form reopens. */ recoveredNotice: string; /** Line under the editor while forms wait in the queue. */ @@ -126,6 +136,16 @@ const EN_STRINGS: AskStrings = { `CORRECTION: the user answered your earlier ask_user form ${formRef(requestId, title)} after it timed out. This replaces the timed-out result, fallbacks included. A question marked (no answer) has none: do not rely on a fallback for it.`, correctionCancelDelivered: (requestId, title) => `CORRECTION: the user cancelled your earlier ask_user form ${formRef(requestId, title)} after it timed out. Any fallback you applied is withdrawn. Cancellation is not approval; keep risky actions blocked.`, + countdownRunning: (remaining, hasFallback) => + hasFallback + ? `⏱ No reply in ${remaining}: the marked fallback will be applied. Press any key to stop the countdown.` + : `⏱ Times out in ${remaining} with no answer applied. Press any key to stop the countdown.`, + countdownStopped: "Countdown stopped; this form now waits for you.", + fallbackOptionMarker: "(fallback)", + lateOverrideBanner: + "This form timed out. Your answer is sent to the agent as a correction.", + expiredIndicator: (count) => + `↺ ${count === 1 ? "1 timed-out form" : `${count} timed-out forms`} can still be answered · /ask-panel`, recoveredNotice: "Reopened a question left unanswered when Pi last stopped", pendingIndicator: ({ focused, forms, key, questions }) => [ @@ -189,6 +209,15 @@ const ZH_STRINGS: AskStrings = { `更正:用户在你之前的 ask_user 表单 ${formRef(requestId, title)} 超时后作出了回答。此回答取代超时结果(包括备选项)。标为(无回答)的问题没有回答,不要依赖其备选项。`, correctionCancelDelivered: (requestId, title) => `更正:用户在你之前的 ask_user 表单 ${formRef(requestId, title)} 超时后取消了它。你应用过的备选项一律撤回。取消不代表批准;有风险的操作仍须保持阻止。`, + countdownRunning: (remaining, hasFallback) => + hasFallback + ? `⏱ ${remaining} 内无回复:将应用标记的备选项。按任意键停止倒计时。` + : `⏱ ${remaining} 后超时,不会应用任何答案。按任意键停止倒计时。`, + countdownStopped: "倒计时已停止;此表单现在等你回答。", + fallbackOptionMarker: "(备选项)", + lateOverrideBanner: "此表单已超时。你的回答会作为更正发送给代理。", + expiredIndicator: (count) => + `↺ ${count} 个已超时的表单仍可回答 · /ask-panel`, recoveredNotice: "已重新打开上次 Pi 停止时未回答的问题", pendingIndicator: ({ focused, forms, key, questions }) => [ diff --git a/pi-ask/src/runtime.ts b/pi-ask/src/runtime.ts index d3042ff5..1f622786 100644 --- a/pi-ask/src/runtime.ts +++ b/pi-ask/src/runtime.ts @@ -1,9 +1,12 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import type { AskBackground } from "./background.ts"; import { type AskJournal, createSessionAskJournal } from "./journal/journal.ts"; +import type { ExpiryClock } from "./state/expiry.ts"; /** State shared by the tool and the lifecycle handlers of one extension load. */ export interface AskRuntime { + /** Time and timers for countdowns; the system clock when absent. */ + clock?: ExpiryClock; /** * Queue, panel and delivery for forms no tool call waits for. Absent when * only the tool is registered: every call then blocks. @@ -18,7 +21,12 @@ export interface AskRuntime { } export function createAskRuntime( - pi: Pick + pi: Pick, + clock?: ExpiryClock ): AskRuntime { - return { journal: createSessionAskJournal(pi), live: new Set() }; + return { + clock, + journal: createSessionAskJournal(pi, clock && { now: clock.now }), + live: new Set(), + }; } diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index df808dbe..bf22e508 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -8,6 +8,7 @@ import { } from "../notifications.ts"; import type { AskDraftSnapshot } from "../journal/entries.ts"; import { createInitialState } from "../state/create.ts"; +import { type ExpiryTimer, toExpiredResult } from "../state/expiry.ts"; import { applyDraftSnapshot } from "../state/draft.ts"; import { getEditorDraft, @@ -74,8 +75,17 @@ export interface AskFlowOptions { * `deferred` result and the caller moves the form to the queue. */ allowDefer?: boolean; + /** Shown under the tabs, e.g. that this form timed out earlier. */ + banner?: string; /** Answers to restore, e.g. from the journal of an interrupted form. */ draft?: AskDraftSnapshot; + /** + * The form's time limit. The flow shows the countdown and stops it on + * the first key. With `owned` it also starts the clock when the form + * opens and finishes with the `expired` result; otherwise the host that + * owns the form's visibility does both. + */ + expiry?: { owned?: boolean; timer: ExpiryTimer }; /** Called for every key the form receives, before it is handled. */ onInput?: (data: string) => void; /** Called after every state change while the form is open. */ @@ -101,11 +111,13 @@ export interface AskFlowComponent { interface AskFlowController { allowDefer: boolean; + banner?: string; config: AskConfig; configNotice?: string; ctx: ExtensionContext; done: Done; editor: Editor; + expiry?: ExpiryTimer; focused: boolean; onInput?: (data: string) => void; onStateChange?: (state: AskState) => void; @@ -155,11 +167,13 @@ export function createAskFlowController( ): AskFlowComponent { const controller: AskFlowController = { allowDefer: params.allowDefer === true, + banner: params.banner, config: params.config, configNotice: params.configNotice, ctx: params.ctx, done, editor: createEditor(tui, theme, params.cwd), + expiry: params.expiry?.timer, focused: false, onInput: params.onInput, onStateChange: params.onStateChange, @@ -191,9 +205,13 @@ export function createAskFlowController( controller.editor.onSubmit = (value) => submitEditor(controller, value); syncSelection(controller); - notifyCurrentQuestion(controller).catch(() => { - // Notification failures are best-effort and must not affect the ask flow. - }); + const unsubscribeExpiry = bindExpiry(controller, params.expiry?.owned === true); + notifyCurrentQuestion(controller) + .catch(() => { + // Notification failures are best-effort and must not affect the ask flow. + }) + // The clock starts only after the user has been told a question waits. + .then(() => controller.expiry?.arm()); return { get focused() { @@ -212,20 +230,47 @@ export function createAskFlowController( controller.editor.invalidate(); }, handleInput(data: string) { + // One key means the user is here: the countdown ends for good. + controller.expiry?.interact(); controller.onInput?.(data); handleControllerInput(controller, data); }, dispose() { + unsubscribeExpiry(); controller.unsubscribeConfig(); }, }; } +/** Redraws on each tick; a form that owns its clock also finishes on expiry. */ +function bindExpiry(controller: AskFlowController, owned: boolean) { + const timer = controller.expiry; + if (!timer) { + return () => { + // nothing to release + }; + } + const unsubscribe = timer.subscribe({ + change: () => controller.tui.requestRender(), + expire: () => { + if (owned && !controller.state.completed) { + controller.done(toExpiredResult(controller.state)); + } + }, + }); + if (owned) { + timer.show(); + } + return unsubscribe; +} + function renderController( controller: AskFlowController, width: number ): string[] { return renderAskScreen({ + banner: controller.banner, + countdown: controller.expiry?.view(), config: controller.config, editor: controller.editor, footerNotice: getFooterNotice(controller), diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts index 5aec1642..bbc3d88f 100644 --- a/pi-ask/src/ui/panel.ts +++ b/pi-ask/src/ui/panel.ts @@ -9,6 +9,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent"; import type { AskConfig } from "../config/schema.ts"; import type { AskDraftSnapshot } from "../journal/entries.ts"; +import type { ExpiryTimer } from "../state/expiry.ts"; import type { AskPanelView } from "../state/panel.ts"; import type { AskParams, AskResult, AskState } from "../types.ts"; import { type AskFlowComponent, createAskFlowController } from "./controller.ts"; @@ -28,8 +29,11 @@ type TuiComponent = Parameters[0]; type FocusAwareTui = Tui & { getFocusedComponent?: () => TuiComponent }; export interface AskPanelForm { + banner?: string; config: AskConfig; draft?: AskDraftSnapshot; + /** Counts down while this form is on screen; see `state/expiry.ts`. */ + expiry?: ExpiryTimer; params: AskParams; requestId: string; } @@ -248,10 +252,12 @@ function createPanelForm( [tui, theme, undefined, (result) => callbacks.onDone(requestId, result)], { ...form.params, + banner: form.banner, config: form.config, ctx, cwd: ctx.cwd, draft: form.draft, + expiry: form.expiry && { timer: form.expiry }, onInput: (data) => callbacks.onInput?.(requestId, data), onStateChange: (state) => callbacks.onStateChange(requestId, state), panel: { onHide: () => callbacks.onHide(requestId) }, diff --git a/pi-ask/src/ui/render-frame.ts b/pi-ask/src/ui/render-frame.ts index c13a6936..748f19b9 100644 --- a/pi-ask/src/ui/render-frame.ts +++ b/pi-ask/src/ui/render-frame.ts @@ -17,10 +17,11 @@ import type { Theme } from "./render-types.ts"; export function renderFrameHeader(args: { lines: string[]; state: AskState; + status?: string; theme: Theme; width: number; }) { - const { lines, state, theme, width } = args; + const { lines, state, status, theme, width } = args; const add = (text = "") => lines.push(truncateToWidth(text, width)); add(theme.fg("accent", "─".repeat(Math.max(1, width)))); @@ -30,6 +31,12 @@ export function renderFrameHeader(args: { } add(renderTabs(state, theme, width)); add(); + if (status) { + for (const line of wrapText(status, Math.max(1, width - 2))) { + add(` ${theme.fg("warning", line)}`); + } + add(); + } } export function renderFrameFooter(args: { diff --git a/pi-ask/src/ui/render-question.ts b/pi-ask/src/ui/render-question.ts index 2ef57fbc..bcace34e 100644 --- a/pi-ask/src/ui/render-question.ts +++ b/pi-ask/src/ui/render-question.ts @@ -4,6 +4,7 @@ import { wrapTextWithAnsi, } from "@earendil-works/pi-tui"; import { UI_DIMENSIONS, UI_TEXT } from "../constants/ui.ts"; +import { askStrings } from "../i18n.ts"; import { pushSavedNote, pushWrappedText, @@ -166,7 +167,8 @@ function renderEditorWithIndent(args: { } function formatOptionLabel(row: OptionRowModel): string { - return `${row.prefix}${row.label}`; + const label = `${row.prefix}${row.label}`; + return row.fallback ? `${label} ${askStrings().fallbackOptionMarker}` : label; } function renderInteractiveCustomOption( diff --git a/pi-ask/src/ui/render-types.ts b/pi-ask/src/ui/render-types.ts index 733aefef..3c2b364c 100644 --- a/pi-ask/src/ui/render-types.ts +++ b/pi-ask/src/ui/render-types.ts @@ -10,6 +10,8 @@ export type Theme = ExtensionContext["ui"]["theme"]; export interface QuestionRenderContext { editor: Editor; + /** The countdown is running: the declared fallback option is marked. */ + fallbackMarked?: boolean; lines: string[]; options: ReturnType; question: NonNullable>; diff --git a/pi-ask/src/ui/render.ts b/pi-ask/src/ui/render.ts index e13d67db..213af547 100644 --- a/pi-ask/src/ui/render.ts +++ b/pi-ask/src/ui/render.ts @@ -1,4 +1,10 @@ import type { AskConfig } from "../config/schema.ts"; +import { askStrings } from "../i18n.ts"; +import { + type ExpiryView, + formatRemaining, + hasDeclaredFallback, +} from "../state/expiry.ts"; import type { FooterSurface } from "../constants/keymaps.ts"; import { getCurrentQuestion, @@ -12,7 +18,11 @@ import { renderSubmitScreen } from "./render-submit.ts"; import type { QuestionRenderContext, Theme } from "./render-types.ts"; export function renderAskScreen(args: { + /** A line under the tabs, e.g. the timed-out notice of a reopened form. */ + banner?: string; config: AskConfig; + /** Present when the form has a time limit. */ + countdown?: ExpiryView; footerNotice?: string; reviewShortcutHint?: string; state: AskState; @@ -22,7 +32,9 @@ export function renderAskScreen(args: { editor: QuestionRenderContext["editor"]; }): string[] { const { + banner, config, + countdown, footerNotice, reviewShortcutHint, state, @@ -35,7 +47,13 @@ export function renderAskScreen(args: { const question = getCurrentQuestion(state); const options = getRenderableOptions(question); - renderFrameHeader({ lines, state, theme, width }); + renderFrameHeader({ + lines, + state, + theme, + width, + status: headerStatus(banner, countdown, state), + }); if (isSubmitTab(state)) { renderSubmitScreen(lines, state, theme, width, reviewShortcutHint); @@ -48,6 +66,7 @@ export function renderAskScreen(args: { theme, width, editor, + fallbackMarked: countdown?.phase === "running", }); } @@ -62,3 +81,23 @@ export function renderAskScreen(args: { }); return lines; } + +/** The one line under the tabs: the countdown, or why the form is special. */ +function headerStatus( + banner: string | undefined, + countdown: ExpiryView | undefined, + state: AskState +): string | undefined { + if (banner) { + return banner; + } + if (countdown?.phase === "running") { + return askStrings().countdownRunning( + formatRemaining(countdown.remainingSeconds), + state.questions.some(hasDeclaredFallback) + ); + } + return countdown?.phase === "stopped" + ? askStrings().countdownStopped + : undefined; +} diff --git a/pi-ask/src/ui/settings-list.ts b/pi-ask/src/ui/settings-list.ts index fc2a3674..371f0edd 100644 --- a/pi-ask/src/ui/settings-list.ts +++ b/pi-ask/src/ui/settings-list.ts @@ -35,7 +35,10 @@ const COMPACT_WIDTH = 40; const RESET_CONFIRMATION_MS = 2000; type SettingSection = "Actions" | "Live settings" | "After /reload"; -type ToggleSettingKey = keyof AskConfig["behaviour"] | "notifications.enabled"; +type ToggleSettingKey = + | keyof AskConfig["behaviour"] + | "notifications.enabled" + | "expiry.enabled"; interface BaseSetting { description: string; @@ -53,7 +56,13 @@ interface ToggleSetting extends BaseSetting { type: "toggle"; } -type Setting = ActionSetting | ToggleSetting; +/** A value shown for reference; it is edited in the config file. */ +interface InfoSetting extends BaseSetting { + key: "expiry.minSeconds"; + type: "info"; +} + +type Setting = ActionSetting | ToggleSetting | InfoSetting; const SETTINGS = [ { @@ -103,6 +112,22 @@ const SETTINGS = [ label: "Background questions", type: "toggle", }, + { + description: + "Let the agent set a time limit on a question, with a declared fallback applied if you do not answer. Any key press stops the countdown. Changing this takes effect after /reload.", + key: "expiry.enabled", + section: "After /reload", + label: "Question expiry", + type: "toggle", + }, + { + description: + "Shortest time limit a question can have; shorter requests are raised to it. Edit expiry.minSeconds in the config file to change it.", + key: "expiry.minSeconds", + section: "After /reload", + label: "Expiry minimum", + type: "info", + }, { description: "Reset behaviour, keymaps, notifications, and extraction settings to defaults. Press twice quickly to confirm.", @@ -331,6 +356,9 @@ export class AskSettingsList { selected ); } + if (setting.type === "info") { + return this.renderValue(`${this.config.expiry.minSeconds}s`, selected); + } return this.renderValue(this.getSettingValue(setting.key), selected); } @@ -343,9 +371,13 @@ export class AskSettingsList { } private getSettingValue(key: SettingKey): boolean { - return key === "notifications.enabled" - ? this.config.notifications.enabled - : this.config.behaviour[key]; + if (key === "notifications.enabled") { + return this.config.notifications.enabled; + } + if (key === "expiry.enabled") { + return this.config.expiry.enabled; + } + return this.config.behaviour[key]; } private moveFocus(delta: 1 | -1): void { @@ -365,6 +397,9 @@ export class AskSettingsList { return; } this.resetConfirmUntil = 0; + if (setting.type === "info") { + return; + } this.saveSetting(setting.key, !this.getSettingValue(setting.key)); this.tui.requestRender(); } @@ -384,23 +419,24 @@ export class AskSettingsList { } private saveSetting(key: SettingKey, enabled: boolean): void { - const nextConfig = - key === "notifications.enabled" - ? { - ...this.config, - notifications: { - ...this.config.notifications, - enabled, - }, - } - : { - ...this.config, - behaviour: { - ...this.config.behaviour, - [key]: enabled, - }, - }; - this.saveConfig(nextConfig); + if (key === "notifications.enabled") { + this.saveConfig({ + ...this.config, + notifications: { ...this.config.notifications, enabled }, + }); + return; + } + if (key === "expiry.enabled") { + this.saveConfig({ + ...this.config, + expiry: { ...this.config.expiry, enabled }, + }); + return; + } + this.saveConfig({ + ...this.config, + behaviour: { ...this.config.behaviour, [key]: enabled }, + }); } private saveConfig(nextConfig: AskConfig): void { diff --git a/pi-ask/src/ui/view-models/question.ts b/pi-ask/src/ui/view-models/question.ts index c45c2247..af5867f5 100644 --- a/pi-ask/src/ui/view-models/question.ts +++ b/pi-ask/src/ui/view-models/question.ts @@ -24,6 +24,8 @@ export interface OptionRowModel { color: "accent" | "text" | "success"; description?: string; detail?: OptionDetailModel; + /** The agent's declared fallback, while its countdown runs. */ + fallback: boolean; index: number; isCustom: boolean; isFreeformOnly: boolean; @@ -79,6 +81,10 @@ function buildOptionRowModel( color: getOptionColor(answered, selected), description: option.description, detail: buildOptionDetailModel(context, option, selected), + fallback: + context.fallbackMarked === true && + !option.isCustomOption && + question.fallback === option.value, index, isCustom: !!option.isCustomOption, isFreeformOnly: !!option.isFreeformOnlyOption, diff --git a/pi-ask/tests/expiry-flow.test.ts b/pi-ask/tests/expiry-flow.test.ts new file mode 100644 index 00000000..dfca946a --- /dev/null +++ b/pi-ask/tests/expiry-flow.test.ts @@ -0,0 +1,473 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { EXPIRED_OFFER_MS, registerAskBackground } from "../src/background.ts"; +import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; +import { getAskConfigStore } from "../src/config/store.ts"; +import { createAskRuntime } from "../src/runtime.ts"; +import { fakeClock } from "./support/fake-clock.ts"; +import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; + +const DB = { + id: "db", + label: "DB", + prompt: "Which database?", + options: [ + { value: "pg", label: "Postgres" }, + { value: "sqlite", label: "SQLite" }, + ], +}; +const CACHE = { + id: "cache", + label: "Cache", + prompt: "Which cache?", + options: [ + { value: "redis", label: "Redis" }, + { value: "none", label: "None" }, + ], +}; +const TIMED = { + title: "Storage", + timeoutSeconds: 60, + questions: [{ ...DB, fallback: "sqlite" }, CACHE], +}; +const PLAIN = { title: "Plain", questions: [DB] }; +const SECOND = 1000; + +function boot( + options: { + clock?: ReturnType; + expiry?: boolean; + session?: SessionManager; + } = {} +) { + const time = options.clock ?? fakeClock(); + const host = fakePi(options.session); + const runtime = createAskRuntime(host.pi, time.clock); + registerAskBackground(host.pi, runtime); + registerAskTool(host.pi, { + runtime, + features: { background: true, expiry: options.expiry ?? true }, + }); + let calls = 0; + const ask = (params: object) => + host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); + const askInBackground = (params: object) => ask({ ...params, background: true }); + return { ...host, host, time, ask, askInBackground }; +} + +type Host = ReturnType; + +async function start(host: Host, reason = "startup") { + host.emit("session_start", { reason }); + await tick(); +} + +const kinds = (host: Host) => host.journal().map((entry) => entry.kind); +const outcomes = (host: Host) => + host.journal().filter((entry) => entry.kind === "outcome"); + +/** A started process with a timed background form on screen. */ +async function withTimedPanel(params: object = TIMED) { + const host = boot(); + await start(host); + const receipt = await host.askInBackground(params); + await tick(); + return { host, requestId: receipt.details.requestId as string }; +} + +beforeEach(quietConfig); + +// --- Blocking forms -------------------------------------------------------- + +test("a blocking form counts down on screen and expires to its declared fallback", async () => { + const host = boot(); + const pending = host.ask(TIMED); + await tick(); + const text = host.forms[0]?.render() ?? ""; + assert.match(text, /No reply in 1:00/); + assert.match(text, /Press any key to stop/); + assert.match(text, /SQLite \(fallback\)/); + assert.doesNotMatch(text, /Postgres \(fallback\)/); + + host.time.advance(59 * SECOND); + assert.match(host.forms[0]?.render() ?? "", /No reply in 0:01/); + host.time.advance(SECOND); + const response = await pending; + + assert.equal(response.details.status, "expired"); + assert.deepEqual(response.details.expired, ["db"]); + assert.deepEqual(response.details.answers.db.values, ["sqlite"]); + assert.deepEqual(response.details.unanswered, ["cache"]); + const result = response.content[0].text; + assert.match(result, /DB: SQLite \[fallback/); + assert.match(result, /Cache: \(no answer\)/); + assert.match(result, /did not respond/); + assert.match(result, /own assumption, not user approval/); + assert.match(result, /irreversible and risky actions blocked/); + assert.equal(outcomes(host).at(-1)?.channel, "tool"); + assert.equal(host.time.pending, 0, "no timer is left behind"); + assert.equal(host.sent.length, 0, "a blocking form needs no follow-up"); +}); + +test("timeoutSeconds below the floor is raised to it, not rejected", async () => { + const host = boot(); + const pending = host.ask({ ...TIMED, timeoutSeconds: 5 }); + await tick(); + assert.equal(host.journal()[0].form.timeoutSeconds, 30); + host.time.advance(29 * SECOND); + assert.equal(host.forms.length, 1); + let settled = false; + pending.then(() => { + settled = true; + }); + await tick(); + assert.equal(settled, false); + host.time.advance(SECOND); + assert.equal((await pending).details.status, "expired"); +}); + +test("the configured floor applies, and a longer request is kept", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { ...DEFAULT_ASK_CONFIG.notifications, enabled: false }, + expiry: { enabled: true, minSeconds: 120 }, + }); + const host = boot(); + host.ask({ ...TIMED, timeoutSeconds: 45 }).catch(() => {}); + host.ask({ ...TIMED, timeoutSeconds: 300 }).catch(() => {}); + await tick(); + assert.deepEqual( + host.journal().map((entry) => entry.form.timeoutSeconds), + [120, 300] + ); +}); + +test("one key stops the countdown for good and the form then waits", async () => { + const host = boot(); + const pending = host.ask(TIMED); + await tick(); + host.time.advance(10 * SECOND); + host.forms[0]?.press(KEY.down); + assert.match(host.forms[0]?.render() ?? "", /Countdown stopped/); + assert.doesNotMatch(host.forms[0]?.render() ?? "", /\(fallback\)/); + assert.ok(kinds(host).includes("expiry")); + assert.equal(host.journal().find((entry) => entry.kind === "expiry").reason, "interaction"); + assert.equal(host.time.pending, 0); + + host.time.advance(24 * 60 * 60 * SECOND); + let settled = false; + pending.then(() => { + settled = true; + }); + await tick(); + assert.equal(settled, false, "an hour of silence later it still waits"); + + host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); + assert.equal((await pending).details.status, "submitted"); +}); + +test("the clock waits for the notification before it starts", async () => { + const host = boot(); + host.ask(TIMED).catch(() => {}); + // The form is on screen but the notification has not fired yet. + assert.equal(host.time.pending, 0); + await tick(); + assert.equal(host.time.pending, 1); +}); + +test("a question with no declared fallback expires with nothing applied", async () => { + const host = boot(); + const pending = host.ask({ ...PLAIN, timeoutSeconds: 30 }); + await tick(); + assert.match(host.forms[0]?.render() ?? "", /Times out in 0:30 with no answer applied/); + host.time.advance(30 * SECOND); + const response = await pending; + assert.equal(response.details.status, "expired"); + assert.deepEqual(response.details.expired, []); + assert.deepEqual(response.details.answers, {}); + assert.match(response.content[0].text, /No fallback was applied/); +}); + +test("an invalid fallback is rejected as invalid", async () => { + const host = boot(); + const response = await host.ask({ + timeoutSeconds: 60, + questions: [{ ...DB, fallback: "mysql" }], + }); + assert.equal(response.details.status, "invalid"); + assert.equal(host.forms.length, 0); +}); + +// --- Expiry switched off --------------------------------------------------- + +test("with expiry disabled the fields leave the schema and a stale call waits", async () => { + const host = boot({ expiry: false }); + const props = host.tools[0].parameters.properties; + assert.ok(!("timeoutSeconds" in props)); + assert.ok(!("fallback" in props.questions.items.properties)); + + const pending = host.ask(TIMED); + await tick(); + assert.doesNotMatch(host.forms[0]?.render() ?? "", /countdown|fallback/i); + assert.equal(host.journal()[0].form.timeoutSeconds, undefined); + assert.equal(host.time.pending, 0); + host.time.advance(24 * 60 * 60 * SECOND); + host.forms[0]?.press(KEY.enter, KEY.enter, KEY.enter); + assert.equal((await pending).details.status, "submitted"); +}); + +test("switching expiry off in the live config stops new countdowns at once", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { ...DEFAULT_ASK_CONFIG.notifications, enabled: false }, + expiry: { enabled: false, minSeconds: 30 }, + }); + const host = boot(); + host.ask(TIMED).catch(() => {}); + await tick(); + assert.equal(host.time.pending, 0); + assert.doesNotMatch(host.forms[0]?.render() ?? "", /countdown/i); +}); + +// --- Background forms ------------------------------------------------------ + +test("a background form that nobody answers expires, wakes the idle agent and says so", async () => { + const { host, requestId } = await withTimedPanel(); + assert.match(host.panelText(), /No reply in 1:00/); + assert.match(host.panelText(), /SQLite \(fallback\)/); + + host.time.advance(60 * SECOND); + const [message] = host.sent; + assert.equal(message?.options?.triggerTurn, true, "an expiry wakes an idle agent"); + assert.match(message?.message.content ?? "", new RegExp(requestId)); + assert.match(message?.message.content ?? "", /timed out/); + assert.match(message?.message.content ?? "", /db "Which database\?": SQLite \[sqlite\] \[fallback/); + assert.match(message?.message.content ?? "", /not user approval/); + assert.equal(message?.message.details.result.status, "expired"); + assert.deepEqual(message?.message.details.result.expired, ["db"]); + assert.equal(outcomes(host).at(-1)?.channel, "message"); + assert.equal(host.panelText(), "", "the expired form left the panel"); + assert.equal(host.time.pending, 0); + + // It is not delivered a second time. + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.sent.length, 1); +}); + +test("an expiry reaches a working agent at its next turn boundary", async () => { + const { host } = await withTimedPanel(); + host.setIdle(false); + host.time.advance(60 * SECOND); + assert.equal(host.sent.length, 0, "nothing interrupts a running turn"); + host.turnEnd(); + assert.equal(host.answers().length, 1); + assert.match(host.answers()[0].content, /timed out/); +}); + +test("a key in the panel stops its countdown", async () => { + const { host } = await withTimedPanel(); + assert.ok(host.focusIs("panel")); + host.time.advance(10 * SECOND); + host.type(KEY.down); + assert.match(host.panelText(), /Countdown stopped/); + host.time.advance(60 * 60 * SECOND); + assert.equal(host.sent.length, 0); + assert.equal(outcomes(host).length, 0); + assert.equal(host.journal().find((entry) => entry.kind === "expiry").reason, "interaction"); +}); + +test("typing in the editor beside an unfocused panel does not stop it", async () => { + const host = boot(); + await start(host); + host.editor.text = "half a message"; + await host.askInBackground(TIMED); + await tick(); + assert.ok(host.focusIs("editor")); + host.type("x"); + host.time.advance(60 * SECOND); + assert.equal(host.sent.length, 1, "the form expired"); +}); + +test("focusing the panel on purpose counts as being there", async () => { + const host = boot(); + await start(host); + host.editor.text = "half a message"; + await host.askInBackground(TIMED); + await tick(); + host.time.advance(10 * SECOND); + host.type(KEY.focus); + assert.match(host.panelText(), /Countdown stopped/); + host.time.advance(60 * 60 * SECOND); + assert.equal(host.sent.length, 0); +}); + +test("a form queued behind another does not count down until it is shown", async () => { + const host = boot(); + await start(host); + await host.askInBackground(PLAIN); + await host.askInBackground({ ...TIMED, title: "Timed", timeoutSeconds: 30 }); + await tick(); + assert.match(host.panelText(), /Plain/); + assert.equal(host.time.pending, 0, "the queued form has no clock yet"); + host.time.advance(10 * 60 * SECOND); + assert.equal(host.sent.length, 0); + + // Answering the first brings the second up with its full limit. + host.type(KEY.enter, KEY.enter); + await tick(); + host.recordWake(); + host.settle(); + assert.match(host.panelText(), /Timed/); + assert.match(host.panelText(), /No reply in 0:30/); + host.time.advance(30 * SECOND); + assert.equal(host.sent.length, 2); + assert.match(host.sent[1]?.message.content ?? "", /timed out/); +}); + +test("a hidden panel does not count down, and hiding a running clock ends it", async () => { + const host = boot(); + await start(host); + host.editor.text = "typing"; + host.setIdle(false); + await host.askInBackground(TIMED); + await tick(); + assert.equal(host.time.pending, 1); + host.type(KEY.focus, KEY.later); + assert.equal(host.panelText(), "", "hidden"); + assert.equal(host.time.pending, 0); + host.time.advance(10 * 60 * SECOND); + assert.equal(host.sent.length, 0); + assert.equal(outcomes(host).length, 0); + + // Bringing it back later gives it no new clock. + host.command("ask-panel"); + assert.match(host.panelText(), /Countdown stopped/); + host.time.advance(60 * 60 * SECOND); + assert.equal(outcomes(host).length, 0); +}); + +test("a blocking form that takes over the keyboard stops the panel's countdown", async () => { + const host = boot(); + await start(host); + host.editor.text = "typing"; + await host.askInBackground(TIMED); + await tick(); + assert.equal(host.time.pending, 1); + const blocking = host.ask(PLAIN); + await tick(); + assert.equal(host.time.pending, 0, "the hidden panel form stopped"); + host.forms[0]?.press(KEY.enter, KEY.enter); + await blocking; + host.time.advance(60 * 60 * SECOND); + assert.equal(outcomes(host).filter((entry) => entry.channel === "message").length, 0); + assert.equal(host.journal().filter((entry) => entry.kind === "expiry")[0].reason, "hidden"); +}); + +test("a form recovered after a restart never counts down", async () => { + const first = await withTimedPanel(); + first.host.emit("session_shutdown"); + const second = boot({ clock: first.host.time, session: first.host.session }); + await start(second, "resume"); + assert.match(second.panelText(), /Storage/); + assert.doesNotMatch(second.panelText(), /countdown|No reply/i); + assert.equal(second.time.pending, 0); + second.time.advance(24 * 60 * 60 * SECOND); + assert.equal(second.sent.length, 0); + assert.equal(outcomes(second).length, 0); +}); + +test("timers are released on shutdown", async () => { + const { host } = await withTimedPanel(); + assert.equal(host.time.pending, 1); + host.emit("session_shutdown"); + assert.equal(host.time.pending, 0); +}); + +// --- Late override --------------------------------------------------------- + +async function expiredBackgroundForm() { + const { host, requestId } = await withTimedPanel(); + host.time.advance(60 * SECOND); + host.recordWake(); + host.settle(); + return { host, requestId }; +} + +test("an expired form is offered, reopens on request and a correction is sent once", async () => { + const { host, requestId } = await expiredBackgroundForm(); + assert.match(host.indicator() ?? "", /1 timed-out form can still be answered/); + assert.match(host.indicator() ?? "", /\/ask-panel/); + assert.equal(host.panelText(), ""); + + host.command("ask-panel"); + assert.match(host.panelText(), /timed out. Your answer is sent to the agent as a correction/); + assert.doesNotMatch(host.panelText(), /countdown|No reply/i); + // Answer DB with Postgres, skip past Cache to the review tab and submit. + host.type(KEY.enter, "\t"); + assert.equal(host.sent.length, 1, "nothing is sent until the form is submitted"); + host.type(KEY.enter); + await tick(); + + assert.equal(host.sent.length, 2); + const correction = host.sent[1]; + assert.equal(correction?.options?.triggerTurn, true); + assert.match(correction?.message.content ?? "", /^CORRECTION: /); + assert.match(correction?.message.content ?? "", new RegExp(requestId)); + assert.match(correction?.message.content ?? "", /replaces the timed-out result, fallbacks included/); + assert.match(correction?.message.content ?? "", /db "Which database\?": Postgres \[pg\]/); + assert.match(correction?.message.content ?? "", /cache "Which cache\?": \(no answer\)/); + assert.doesNotMatch(correction?.message.content ?? "", /\[fallback/); + assert.equal(correction?.message.details.correction, true); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined, "the offer is over once corrected"); + + host.recordWake(); + host.settle(); + await start(host, "reload"); + host.command("ask-panel"); + assert.equal(host.sent.length, 2, "exactly once, across a reload too"); + assert.ok(host.notices.at(-1)?.includes("No questions are waiting")); +}); + +test("closing a reopened expired form without an answer ends the offer silently", async () => { + const { host } = await expiredBackgroundForm(); + host.command("ask-panel"); + host.type(KEY.ctrlC); + await tick(); + assert.equal(host.sent.length, 1, "no message for a bare dismissal"); + assert.equal(host.indicator(), undefined); + assert.equal(host.panelText(), ""); + await start(host, "reload"); + assert.equal(host.indicator(), undefined, "still gone after a reload"); + assert.ok(kindsOf(host).includes("dismiss")); +}); + +const kindsOf = (host: Host) => host.journal().map((entry) => entry.kind); + +test("the offer lapses after an hour", async () => { + const { host } = await expiredBackgroundForm(); + host.time.advance(EXPIRED_OFFER_MS + SECOND); + host.command("ask-panel"); + assert.ok(host.notices.at(-1)?.includes("No questions are waiting")); + assert.equal(host.panelText(), ""); +}); + +test("a blocking form that expired can be corrected late too", async () => { + const host = boot(); + const pending = host.ask(TIMED); + await tick(); + host.time.advance(60 * SECOND); + await pending; + assert.match(host.indicator() ?? "", /timed-out form/); + + host.command("ask-panel"); + host.type(KEY.enter, KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.match(host.sent[0]?.message.content ?? "", /^CORRECTION: /); + assert.equal(outcomes(host).at(-1)?.supersedes, outcomes(host)[0].outcomeId); +}); diff --git a/pi-ask/tests/expiry.test.ts b/pi-ask/tests/expiry.test.ts index cb07cbb1..203d38d1 100644 --- a/pi-ask/tests/expiry.test.ts +++ b/pi-ask/tests/expiry.test.ts @@ -5,50 +5,11 @@ import { applyFallbacks, createExpiryTimer, effectiveTimeoutSeconds, - type ExpiryClock, formatRemaining, toExpiredResult, } from "../src/state/expiry.ts"; import type { AskParams } from "../src/types.ts"; - -/** A clock that moves only when told to; timers fire in order. */ -function fakeClock() { - let now = 1_000_000; - let next = 1; - const timers = new Map void }>(); - const clock: ExpiryClock = { - now: () => now, - setTimeout(task, ms) { - const id = next++; - timers.set(id, { at: now + ms, task }); - return id; - }, - clearTimeout(handle) { - timers.delete(handle as number); - }, - }; - return { - clock, - get pending() { - return timers.size; - }, - advance(ms: number) { - const end = now + ms; - for (;;) { - const due = [...timers.entries()] - .filter(([, timer]) => timer.at <= end) - .sort((a, b) => a[1].at - b[1].at)[0]; - if (!due) { - break; - } - timers.delete(due[0]); - now = Math.max(now, due[1].at); - due[1].task(); - } - now = end; - }, - }; -} +import { fakeClock } from "./support/fake-clock.ts"; function record(timer: ReturnType) { const events: string[] = []; diff --git a/pi-ask/tests/settings-list.test.ts b/pi-ask/tests/settings-list.test.ts index 3af3c05d..d4f6453d 100644 --- a/pi-ask/tests/settings-list.test.ts +++ b/pi-ask/tests/settings-list.test.ts @@ -243,3 +243,33 @@ test("settings list closes with configured keys and dispose idempotently", () => list.dispose(); assert.equal(closed, 1); }); + +test("settings list toggles expiry, notes it applies on reload, and shows the floor", async () => { + const saves: AskConfig[] = []; + const list = createList({ + onSave: (config) => { + saves.push(config); + return Promise.resolve(config); + }, + }); + const text = list.render(72).join("\n"); + assert(text.includes("After /reload")); + assert(text.includes("Question expiry")); + assert(text.includes("Expiry minimum")); + assert(text.includes("[30s]")); + + for (let index = 0; index < 6; index++) { + list.handleInput("\u001b[B"); + } + assert(list.render(72).join("\n").includes("takes effect after /reload")); + list.handleInput(" "); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(saves.at(-1)?.expiry.enabled, false); + assert.equal(saves.at(-1)?.expiry.minSeconds, 30); + + // The floor is shown for reference; toggling it saves nothing. + list.handleInput("\u001b[B"); + list.handleInput(" "); + await new Promise((resolve) => setImmediate(resolve)); + assert.equal(saves.length, 1); +}); diff --git a/pi-ask/tests/support/fake-clock.ts b/pi-ask/tests/support/fake-clock.ts new file mode 100644 index 00000000..9645e09d --- /dev/null +++ b/pi-ask/tests/support/fake-clock.ts @@ -0,0 +1,41 @@ +import type { ExpiryClock } from "../../src/state/expiry.ts"; + +/** A clock that moves only when told to; due timers fire in order. */ +export function fakeClock() { + let now = 1_700_000_000_000; + let next = 1; + const timers = new Map void }>(); + const clock: ExpiryClock = { + now: () => now, + setTimeout(task, ms) { + const id = next++; + timers.set(id, { at: now + ms, task }); + return id; + }, + clearTimeout(handle) { + timers.delete(handle as number); + }, + }; + return { + clock, + /** Timers still scheduled; zero means nothing is left running. */ + get pending() { + return timers.size; + }, + advance(ms: number) { + const end = now + ms; + for (;;) { + const due = [...timers.entries()] + .filter(([, timer]) => timer.at <= end) + .sort((a, b) => a[1].at - b[1].at)[0]; + if (!due) { + break; + } + timers.delete(due[0]); + now = Math.max(now, due[1].at); + due[1].task(); + } + now = end; + }, + }; +} diff --git a/pi-ask/tests/token-ceiling.test.ts b/pi-ask/tests/token-ceiling.test.ts index 00c09b54..fd932da5 100644 --- a/pi-ask/tests/token-ceiling.test.ts +++ b/pi-ask/tests/token-ceiling.test.ts @@ -45,7 +45,6 @@ test("ask_user footprint stays under the lower ceiling with expiry disabled", () for (const features of [ { ...ALL_ASK_FEATURES, expiry: false }, NO_ASK_FEATURES, - SHIPPED_ASK_FEATURES, ]) { const { totalTokens } = measureAskToolFootprint({ features }); assert.ok( @@ -55,6 +54,14 @@ test("ask_user footprint stays under the lower ceiling with expiry disabled", () } }); +test("everything that ships fits the all-enabled ceiling", () => { + assert.deepEqual(SHIPPED_ASK_FEATURES, ALL_ASK_FEATURES); + const { totalTokens } = measureAskToolFootprint({ + features: SHIPPED_ASK_FEATURES, + }); + assert.ok(totalTokens <= CEILING_ALL_ENABLED); +}); + test("a disabled feature is absent from the registered schema", () => { assert.deepEqual(schemaKeys(NO_ASK_FEATURES), { call: ["title", "questions"], diff --git a/scripts/packages.mjs b/scripts/packages.mjs index ea2d35a5..7adecd63 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,7 +2,7 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "expiry-flow.test.ts"], commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled"], }, From 60d98459822a19a886753a6bb28bad5126833984 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 01:06:42 +0000 Subject: [PATCH 16/38] docs(ask): describe expiry, the stopped clock and late override --- pi-ask/README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/pi-ask/README.md b/pi-ask/README.md index ff165712..67f58055 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -51,13 +51,30 @@ A background question, a form you deferred, and a form left open when Pi last st Both keys are `keymaps.global.later` and `keymaps.global.panelFocus` in the config file. +### Questions that expire + +An agent that expects you to be away can give a call `timeoutSeconds` and mark one option per question as its `fallback`. If you do not respond in time, the form resolves as `expired`: declared fallbacks are applied and the rest stay unanswered. A fallback is the agent's own assumption, never your approval; the result says so and keeps irreversible or risky actions blocked. + +The clock is built to be hard to trip: + +- It runs only while the form is on screen, after the notification has fired. A form waiting behind another, or in a hidden panel, does not count down. The form shows the countdown and marks the fallback option. +- **Any key you press in the form stops it for good**, as does opening or focusing the panel on purpose. A stopped form waits like a normal one, and the stop is journalled, so a reload cannot restart it. Typing in the input beside an unfocused panel does not stop it: the countdown is on screen. +- Hiding the panel, deferring, or a blocking form taking over also stops a running clock for good. Nothing pauses and resumes. +- A form that comes back after Pi restarted (resume, fork, reload) never counts down. You had no fair chance to see its clock. +- `expiry.minSeconds` (30) is a floor: shorter requests are raised, never rejected. +- A background form that expires is delivered like an answer, and it wakes an idle agent: the agent asked for a time-boxed fallback so that an unattended run finishes. A cancellation still never wakes it. +- With expiry off (`expiry.enabled: false`, applies on `/reload`) both fields are absent from the schema, and a stale call that still carries them waits indefinitely. +- Hosts without the custom TUI (RPC cards, ACP) have no countdown. The call waits as it does today. + +**Late override.** An expired form stays reopenable: a line under the input says so, and `/ask-panel` brings it back with a notice. Submitting sends a correction as a follow-up that names the request, says it replaces the timed-out result (fallbacks included), and is delivered once. `Ctrl+C` on the reopened form without a comment dismisses it silently and leaves the agent's earlier result as it was. The offer ends when you correct or dismiss it, or one hour after the expiry. + ### Commands | Command | What it does | | --- | --- | | `/answer` | Turn the latest completed assistant message into a form | | `/ask-settings` | Settings overlay. `?` inside a form opens the same overlay | -| `/ask-panel` | Show the waiting questions and move the keyboard to them | +| `/ask-panel` | Show the waiting questions, and any timed-out ones you can still answer, and move the keyboard to them | Hosts without the custom TUI (RPC subagents, ACP clients) get the same interview as sequential select/input cards with back navigation and a review card; a background call blocks there, and there is no "answer later". Callers with no dialog UI at all get `status: "unavailable"`. @@ -98,7 +115,7 @@ Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the curren Schema settings apply on `/reload`, not live. A disabled field is absent from the schema, not ignored. -> Unreleased: this is the 0.2.0 contract. `background`, `queued` and `deferred` work on this branch; `timeoutSeconds`, `fallback` and `expired` are not registered yet. +> Unreleased: this is the 0.2.0 contract. `background`, `queued`, `deferred`, `timeoutSeconds`, `fallback` and `expired` work on this branch. `/ask-settings` toggles expiry (after `/reload`) and shows the floor. ## Context footprint From d5c59f441d8244a9ce7c2aeb388e72f3b44f5019 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 01:10:51 +0000 Subject: [PATCH 17/38] feat(ask): skip one question and cancel with a comment s skips the current question (answer and notes dropped, listed in skipped, marked on the tab and the review). c on the review tab attaches a comment to Cancel, carried in the cancelled result and the delivered message. Neither key fires inside a text editor; both are keymap entries with footer hints. --- pi-ask/src/config/schema.ts | 6 + pi-ask/src/constants/keymaps.ts | 12 ++ pi-ask/src/constants/ui.ts | 4 + pi-ask/src/delivery.ts | 19 +- pi-ask/src/i18n.ts | 24 +++ pi-ask/src/journal/entries.ts | 2 + pi-ask/src/result-format.ts | 15 ++ pi-ask/src/result.ts | 4 +- pi-ask/src/state/draft.ts | 9 +- pi-ask/src/state/editor.ts | 10 +- pi-ask/src/state/result.ts | 35 +++- pi-ask/src/state/transitions.ts | 57 ++++++ pi-ask/src/state/view.ts | 10 +- pi-ask/src/types.ts | 4 +- pi-ask/src/ui/controller.ts | 17 +- pi-ask/src/ui/dismiss-guard.ts | 6 +- pi-ask/src/ui/input.ts | 13 +- pi-ask/src/ui/render-frame.ts | 8 +- pi-ask/src/ui/render-question.ts | 11 ++ pi-ask/src/ui/render-submit.ts | 41 ++++- pi-ask/src/ui/render.ts | 2 +- pi-ask/src/ui/view-models/review.ts | 12 +- pi-ask/tests/render-frame.test.ts | 4 +- pi-ask/tests/skip-cancel-flow.test.ts | 189 ++++++++++++++++++++ pi-ask/tests/skip-cancel.test.ts | 248 ++++++++++++++++++++++++++ pi-ask/tests/support/fake-pi.ts | 1 + scripts/packages.mjs | 2 +- 27 files changed, 739 insertions(+), 26 deletions(-) create mode 100644 pi-ask/tests/skip-cancel-flow.test.ts create mode 100644 pi-ask/tests/skip-cancel.test.ts diff --git a/pi-ask/src/config/schema.ts b/pi-ask/src/config/schema.ts index aeae11ae..54e5a949 100644 --- a/pi-ask/src/config/schema.ts +++ b/pi-ask/src/config/schema.ts @@ -30,6 +30,7 @@ const AskConfigKeymapsSchema = Type.Object({ }), main: Type.Object({ cancel: Type.Optional(AskKeyBindingSchema), + cancelComment: Type.Optional(AskKeyBindingSchema), changeQuestionType: Type.Optional(AskKeyBindingSchema), confirm: Type.Optional(AskKeyBindingSchema), nextOption: Type.Optional(AskKeyBindingSchema), @@ -38,6 +39,7 @@ const AskConfigKeymapsSchema = Type.Object({ previousOption: Type.Optional(AskKeyBindingSchema), previousTab: Type.Optional(AskKeyBindingSchema), questionNote: Type.Optional(AskKeyBindingSchema), + skip: Type.Optional(AskKeyBindingSchema), toggle: Type.Optional(AskKeyBindingSchema), }), editor: Type.Object({ @@ -124,6 +126,8 @@ export interface AskConfigKeymaps { }; main: { cancel: string[]; + /** Review tab: cancel the form and say why. */ + cancelComment: string[]; changeQuestionType: string[]; confirm: string[]; nextOption: string[]; @@ -132,6 +136,8 @@ export interface AskConfigKeymaps { previousOption: string[]; previousTab: string[]; questionNote: string[]; + /** Skip just the current question. Never fires inside a text editor. */ + skip: string[]; toggle: string[]; }; noteEditor: { diff --git a/pi-ask/src/constants/keymaps.ts b/pi-ask/src/constants/keymaps.ts index 9d6beefc..96fac4b6 100644 --- a/pi-ask/src/constants/keymaps.ts +++ b/pi-ask/src/constants/keymaps.ts @@ -80,6 +80,7 @@ export interface AskKeyBinding { } export type FooterKeymapContext = + | "comment" | "default" | "multi" | "submit" @@ -104,6 +105,8 @@ export const DEFAULT_ASK_KEYMAPS: AskConfigKeymaps = { previousOption: ["up"], optionNote: ["n"], questionNote: ["shift+n"], + skip: ["s"], + cancelComment: ["c"], }, editor: { submit: ["enter"], @@ -147,6 +150,8 @@ const DESCRIPTIONS: Record> = { previousOption: "Move to previous option/action", optionNote: "Edit selected option note", questionNote: "Edit question note", + skip: "Skip the current question without cancelling", + cancelComment: "Cancel the form with a comment (review tab)", }, editor: { submit: "Submit custom answer", @@ -318,6 +323,10 @@ export function renderFooterKeymaps( footerHint(editor.close, "close"), footerHint(global.settings, "settings"), ], + comment: [ + footerHint(noteEditor.save, "cancel with comment"), + footerHint(noteEditor.close, "back"), + ], note: [ footerHint(noteEditor.save, "save"), footerHint(noteEditor.close, "close"), @@ -326,12 +335,14 @@ export function renderFooterKeymaps( submit: [ footerHint(main.confirm, "confirm"), footerHint(main.cancel, "cancel"), + footerHint(main.cancelComment, "cancel with comment"), footerHint(global.settings, "settings"), ], multi: [ footerHint(main.toggle, "toggle"), footerHint(main.confirm, "continue"), footerHint(main.optionNote, "note", noteNavigationLabel), + footerHint(main.skip, "skip"), footerHint(main.cancel, "dismiss"), footerHint( main.changeQuestionType, @@ -343,6 +354,7 @@ export function renderFooterKeymaps( default: [ footerHint(main.confirm, "confirm"), footerHint(main.optionNote, "note", noteNavigationLabel), + footerHint(main.skip, "skip"), footerHint(main.cancel, "dismiss"), footerHint( main.changeQuestionType, diff --git a/pi-ask/src/constants/ui.ts b/pi-ask/src/constants/ui.ts index ba48567d..643df903 100644 --- a/pi-ask/src/constants/ui.ts +++ b/pi-ask/src/constants/ui.ts @@ -12,6 +12,10 @@ export const UI_TEXT = { questionNoteTitle: "Note:", reviewTitle: "Review answers", unanswered: "→ unanswered", + skipped: "→ skipped (declined, not unanswered)", + skippedQuestion: "⊘ Skipped. Answer it to take the skip back.", + commentTitle: "Why are you cancelling? The agent will see this.", + editorPlaceholderComment: "Add a comment (optional)...", editorPlaceholderInput: "Type answer...", editorPlaceholderNote: "Add a note...", } as const; diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 0fe837ce..2203af94 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -83,6 +83,7 @@ export function formatDeliveredOutcome( heading = strings.expiredDelivered(requestId, result.title); } const fallbacks = new Set(result.expired ?? []); + const skipped = new Set(result.skipped ?? []); // Each question is named by id and prompt: the call that asked may be // far back in the context, or compacted away. const lines = result.questions.map((question) => { @@ -90,10 +91,13 @@ export function formatDeliveredOutcome( if (cancelled) { return asked; } + if (skipped.has(question.id)) { + return `${asked}: ${strings.skippedMark}`; + } const answer = formatAnswer(result.answers[question.id]); return `${asked}: ${answer}${fallbacks.has(question.id) ? ` ${strings.fallbackMark}` : ""}`; }); - const trailer = expired + const trailer: string[] = expired ? [ strings.expiredSummary( result.questions @@ -102,7 +106,18 @@ export function formatDeliveredOutcome( ), ] : []; - return [heading, ...lines, ...trailer].join("\n"); + if (skipped.size > 0 && !cancelled) { + trailer.push( + strings.skippedSummary( + result.questions + .filter((question) => skipped.has(question.id)) + .map((question) => question.label) + ) + ); + } + const reason = + cancelled && result.comment ? [strings.cancelReason(result.comment)] : []; + return [heading, ...reason, ...lines, ...trailer].join("\n"); } function formatAnswer(answer: AskResultAnswer | undefined): string { diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index ca47307b..1e23c893 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -29,6 +29,14 @@ export interface AskStrings { cancelledSummary: string; /** One-line summary returned to the model when the user submits. */ submittedSummary: string; + /** The user cancelled and said why. */ + cancelledWithComment: (comment: string) => string; + /** Appended to an answer line for a question the user skipped. */ + skippedMark: string; + /** Trailer naming the skipped questions and what a skip means. */ + skippedSummary: (labels: string[]) => string; + /** The reason line of a delivered cancellation. */ + cancelReason: (comment: string) => string; /** Receipt returned to the model for a background call. */ queuedSummary: (requestId: string, pending?: number) => string; /** Receipt returned to the model when the user chose "answer later". */ @@ -94,6 +102,10 @@ function count(value: number, noun: string): string { return `${value} ${noun}${value === 1 ? "" : "s"}`; } +function oneLine(text: string): string { + return text.replace(/\s+/g, " ").trim(); +} + function formRef(requestId: string, title?: string): string { return title ? `${requestId} (${title})` : requestId; } @@ -111,6 +123,12 @@ const EN_STRINGS: AskStrings = { recommendedMarker: "(Recommended)", cancelledSummary: "User cancelled the ask flow", submittedSummary: "User submitted the ask flow", + cancelledWithComment: (comment) => + `User cancelled the ask flow. Reason: "${oneLine(comment)}". Cancellation is not approval; keep risky actions blocked.`, + skippedMark: "(skipped by the user)", + skippedSummary: (labels) => + `The user skipped: ${labels.join(", ")}. A skip declines the question: it is not approval and not an answer, so do not assume one.`, + cancelReason: (comment) => `The user's reason: "${oneLine(comment)}".`, queuedSummary: (requestId, pending) => `Queued as ${requestId}${ pending && pending > 1 ? ` (${pending} forms waiting)` : "" @@ -184,6 +202,12 @@ const ZH_STRINGS: AskStrings = { recommendedMarker: "(推荐)", cancelledSummary: "用户取消了提问流程", submittedSummary: "用户提交了提问流程", + cancelledWithComment: (comment) => + `用户取消了提问流程。原因:“${oneLine(comment)}”。取消不代表批准;有风险的操作仍须保持阻止。`, + skippedMark: "(用户已跳过)", + skippedSummary: (labels) => + `用户跳过了:${labels.join("、")}。跳过表示拒绝回答该问题:它不是批准,也不是回答,不要自行假定答案。`, + cancelReason: (comment) => `用户给出的原因:“${oneLine(comment)}”。`, queuedSummary: (requestId, pending) => `已排队,编号 ${requestId}${ pending && pending > 1 ? `(共 ${pending} 个表单待回答)` : "" diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts index 6c28f7cd..55aac535 100644 --- a/pi-ask/src/journal/entries.ts +++ b/pi-ask/src/journal/entries.ts @@ -39,6 +39,8 @@ export interface AskFormSnapshot { export interface AskDraftSnapshot { activeTabIndex?: number; answers: Record; + /** Question ids the user skipped. */ + skipped?: string[]; /** Present only when the user changed a question's presented type. */ questions?: AskQuestion[]; } diff --git a/pi-ask/src/result-format.ts b/pi-ask/src/result-format.ts index 054c2559..480f1f28 100644 --- a/pi-ask/src/result-format.ts +++ b/pi-ask/src/result-format.ts @@ -10,9 +10,14 @@ export function formatResultLines( let hasPresentationOverride = false; const fallbacks = new Set(result.expired ?? []); + const skipped = new Set(result.skipped ?? []); for (const question of result.questions) { const answer = result.answers[question.id]; + if (skipped.has(question.id)) { + lines.push(formatSkippedLine(question.label, options.mode)); + continue; + } if (!answer) { lines.push(formatUnansweredLine(question.label, options.mode)); continue; @@ -53,6 +58,16 @@ function markFallback(line: string, isFallback: boolean): string { return isFallback ? `${line} ${askStrings().fallbackMark}` : line; } +function formatSkippedLine( + questionLabel: string, + mode: "summary" | "render" +): string { + const mark = askStrings().skippedMark; + return mode === "summary" + ? `${questionLabel}: ${mark}` + : `⊘ ${questionLabel}: ${mark}`; +} + function formatUnansweredLine( questionLabel: string, mode: "summary" | "render" diff --git a/pi-ask/src/result.ts b/pi-ask/src/result.ts index d4565a51..f77d198d 100644 --- a/pi-ask/src/result.ts +++ b/pi-ask/src/result.ts @@ -11,7 +11,9 @@ export function renderResultText(result: AskResult): string { return "Invalid tool payload"; } if (result.status === "cancelled") { - return CANCELLED_RESULT_TEXT; + return result.comment + ? `${CANCELLED_RESULT_TEXT}: ${result.comment}` + : CANCELLED_RESULT_TEXT; } if (result.status === "unavailable") { return "Needs user input"; diff --git a/pi-ask/src/state/draft.ts b/pi-ask/src/state/draft.ts index 2a09db36..d0e12e51 100644 --- a/pi-ask/src/state/draft.ts +++ b/pi-ask/src/state/draft.ts @@ -9,6 +9,7 @@ export function toDraftSnapshot(state: AskState): AskDraftSnapshot { ); return { answers: structuredClone(state.answers), + ...(state.skipped?.length ? { skipped: [...state.skipped] } : {}), activeTabIndex: state.activeTabIndex, ...(typeChanged ? { questions: structuredClone(state.questions) } : {}), }; @@ -42,10 +43,12 @@ export function applyDraftSnapshot( typeof tab === "number" && Number.isInteger(tab) ? Math.max(0, Math.min(tab, ids.length)) : state.activeTabIndex; + const skipped = ids.filter((id) => draft.skipped?.includes(id)); return { ...state, questions, answers: structuredClone(answers), + ...(skipped.length > 0 ? { skipped } : {}), activeTabIndex, view: activeTabIndex >= ids.length ? submitView() : navigateView(), }; @@ -53,5 +56,9 @@ export function applyDraftSnapshot( /** Changes in this key are worth a journal entry; cursor moves are not. */ export function draftContentKey(draft: AskDraftSnapshot): string { - return JSON.stringify([draft.answers, draft.questions ?? null]); + return JSON.stringify([ + draft.answers, + draft.questions ?? null, + draft.skipped ?? null, + ]); } diff --git a/pi-ask/src/state/editor.ts b/pi-ask/src/state/editor.ts index 77e2d702..c64bdd4e 100644 --- a/pi-ask/src/state/editor.ts +++ b/pi-ask/src/state/editor.ts @@ -8,12 +8,13 @@ import { isSubmitTab, } from "./selectors.ts"; import { + cancelWithComment, enterInputMode, saveCustomAnswer, saveNote, submitCustomAnswer, } from "./transitions.ts"; -import { isEditingView } from "./view.ts"; +import { isEditingView, submitView } from "./view.ts"; export function getEditorDraft(state: AskState): string { if (state.view.kind === "input") { @@ -38,6 +39,10 @@ export function saveEditorDraft(state: AskState, text: string): AskState { if (state.view.kind === "note") { return saveNote(state, text); } + if (state.view.kind === "comment") { + // Closing the comment editor never cancels, and keeps no stale reason. + return { ...state, view: submitView() }; + } return state; } @@ -48,6 +53,9 @@ export function submitEditorDraft(state: AskState, text: string): AskState { if (state.view.kind === "note") { return saveNote(state, text); } + if (state.view.kind === "comment") { + return cancelWithComment(state, text); + } return state; } diff --git a/pi-ask/src/state/result.ts b/pi-ask/src/state/result.ts index 4d0e9ccd..e25bf2b9 100644 --- a/pi-ask/src/state/result.ts +++ b/pi-ask/src/state/result.ts @@ -24,7 +24,7 @@ export type ReviewAnswer = AskResult["answers"][string] & { export function toAskResult( state: AskState, - status?: AskResultStatus + requested?: AskResultStatus ): AskResult { const answers = Object.fromEntries( Object.entries(state.answers) @@ -33,13 +33,24 @@ export function toAskResult( ) .filter(([, answer]) => !isResultAnswerEmpty(answer)) ); + const skipped = state.questions + .map((question) => question.id) + .filter((id) => state.skipped?.includes(id)); + // Skipped is a decision, not a gap: the two lists never overlap. const unanswered = state.questions - .filter((question) => !isResultAnswerCommitted(answers[question.id] ?? emptyResultAnswer())) + .filter( + (question) => + !( + skipped.includes(question.id) || + isResultAnswerCommitted(answers[question.id] ?? emptyResultAnswer()) + ) + ) .map((question) => question.id); + const status = requested ?? resultStatusFromState(state); return { title: state.title, - status: status ?? resultStatusFromState(state), + status, questions: state.questions.map((question) => ({ id: question.id, label: question.label, @@ -52,12 +63,18 @@ export function toAskResult( })), answers, unanswered, + ...(skipped.length > 0 ? { skipped } : {}), + ...(status === "cancelled" && state.cancelComment + ? { comment: state.cancelComment } + : {}), }; } export function summarizeResult(result: AskResult): string { if (result.status === "cancelled") { - return askStrings().cancelledSummary; + return result.comment + ? askStrings().cancelledWithComment(result.comment) + : askStrings().cancelledSummary; } if (result.status === "unavailable") { return "Needs user input"; @@ -75,6 +92,9 @@ export function summarizeResult(result: AskResult): string { } const lines = formatResultLines(result, { mode: "summary" }); + if (result.skipped?.length) { + lines.push(askStrings().skippedSummary(skippedLabels(result))); + } if (result.status === "expired") { lines.push(askStrings().expiredSummary(expiredLabels(result))); return lines.join("\n"); @@ -82,6 +102,13 @@ export function summarizeResult(result: AskResult): string { return lines.join("\n") || askStrings().submittedSummary; } +function skippedLabels(result: AskResult): string[] { + const skipped = new Set(result.skipped ?? []); + return result.questions + .filter((question) => skipped.has(question.id)) + .map((question) => question.label); +} + function expiredLabels(result: AskResult): string[] { const expired = new Set(result.expired ?? []); return result.questions diff --git a/pi-ask/src/state/transitions.ts b/pi-ask/src/state/transitions.ts index 82588f05..185568c1 100644 --- a/pi-ask/src/state/transitions.ts +++ b/pi-ask/src/state/transitions.ts @@ -20,6 +20,7 @@ import { isSubmitTab, } from "./selectors.ts"; import { + commentView, inputView, navigateView, optionNoteView, @@ -48,6 +49,59 @@ export function enterOptionNoteMode( return setView(state, optionNoteView(questionId, optionValue)); } +/** Longest cancel comment kept; it is a short reason, not a message. */ +export const MAX_CANCEL_COMMENT_LENGTH = 500; + +/** Review tab only: start typing a reason for cancelling. */ +export function enterCancelComment(state: AskState): AskState { + return isSubmitTab(state) ? setView(state, commentView()) : state; +} + +/** + * Cancel with the typed reason. An empty comment cancels nothing: it goes + * back to the review tab, so an accidental Enter is not a cancellation. + */ +export function cancelWithComment(state: AskState, text: string): AskState { + const comment = text.trim().slice(0, MAX_CANCEL_COMMENT_LENGTH); + if (!comment) { + return { ...state, view: submitView() }; + } + return { + ...state, + cancelComment: comment, + cancelled: true, + completed: true, + view: submitView(), + }; +} + +/** + * Decline just the current question: its answer and notes are dropped and + * the form moves on. The form itself stays open, and skipping every + * question still ends at the review tab for an explicit submit. + */ +export function skipCurrentQuestion(state: AskState): AskState { + const question = getCurrentQuestion(state); + if (!question || isSubmitTab(state)) { + return state; + } + const answers = { ...state.answers }; + delete answers[question.id]; + const skipped = new Set(state.skipped ?? []); + skipped.add(question.id); + return advanceToNextTab({ + ...state, + answers, + skipped: orderedSkipped(state, skipped), + }); +} + +function orderedSkipped(state: AskState, skipped: ReadonlySet) { + return state.questions + .map((question) => question.id) + .filter((id) => skipped.has(id)); +} + export function toggleCurrentMultiOption(state: AskState): AskState { return activateCurrentOption(state, "toggle"); } @@ -251,8 +305,11 @@ function updateAnswer( } else { answers[questionId] = nextAnswer; } + // Answering a skipped question takes the skip back. + const skipped = state.skipped?.filter((id) => id !== questionId); return { ...state, answers, + ...(state.skipped ? { skipped } : {}), }; } diff --git a/pi-ask/src/state/view.ts b/pi-ask/src/state/view.ts index c218b0e1..dfce7845 100644 --- a/pi-ask/src/state/view.ts +++ b/pi-ask/src/state/view.ts @@ -23,6 +23,14 @@ export function optionNoteView( return { kind: "note", questionId, optionValue }; } +export function commentView(): ViewState { + return { kind: "comment" }; +} + export function isEditingView(state: AskState): boolean { - return state.view.kind === "input" || state.view.kind === "note"; + return ( + state.view.kind === "input" || + state.view.kind === "note" || + state.view.kind === "comment" + ); } diff --git a/pi-ask/src/types.ts b/pi-ask/src/types.ts index c378ec3b..e9397354 100644 --- a/pi-ask/src/types.ts +++ b/pi-ask/src/types.ts @@ -111,7 +111,9 @@ export type ViewState = | { kind: "navigate" } | { kind: "submit" } | { kind: "input"; questionId: string } - | { kind: "note"; questionId: string; optionValue?: string }; + | { kind: "note"; questionId: string; optionValue?: string } + /** Typing why the form is being cancelled, on the review tab. */ + | { kind: "comment" }; export interface AskState { activeOptionIndex: number; diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index bf22e508..ea292131 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -32,8 +32,10 @@ import { import { applyNumberShortcut, confirmCurrentSelection, + enterCancelComment, enterOptionNoteMode, enterQuestionNoteMode, + skipCurrentQuestion, toggleCurrentMultiOption, } from "../state/transitions.ts"; import { isEditingView } from "../state/view.ts"; @@ -303,7 +305,10 @@ function isNativeEditorSubmitEnabled(controller: AskFlowController): boolean { if (controller.state.view.kind === "input") { return controller.config.keymaps.editor.submit.includes("enter"); } - if (controller.state.view.kind === "note") { + if ( + controller.state.view.kind === "note" || + controller.state.view.kind === "comment" + ) { return controller.config.keymaps.noteEditor.save.includes("enter"); } return true; @@ -369,6 +374,16 @@ function handleNavigationCommand( clearPendingConfirms(controller, { keepTypeChange: true }); handleChangeQuestionType(controller); return; + case "skipQuestion": + clearPendingConfirms(controller); + commitState(controller, skipCurrentQuestion(controller.state)); + return; + case "cancelWithComment": + clearPendingConfirms(controller); + commitState(controller, enterCancelComment(controller.state), { + syncSelection: false, + }); + return; case "openQuestionNote": clearPendingConfirms(controller); openQuestionNote(controller); diff --git a/pi-ask/src/ui/dismiss-guard.ts b/pi-ask/src/ui/dismiss-guard.ts index 4ea66f59..4e577676 100644 --- a/pi-ask/src/ui/dismiss-guard.ts +++ b/pi-ask/src/ui/dismiss-guard.ts @@ -16,5 +16,9 @@ export function shouldConfirmDirtyDismiss(args: { } export function hasDirtyFlowState(state: AskState, editingText = ""): boolean { - return Object.keys(state.answers).length > 0 || editingText.length > 0; + return ( + Object.keys(state.answers).length > 0 || + (state.skipped?.length ?? 0) > 0 || + editingText.length > 0 + ); } diff --git a/pi-ask/src/ui/input.ts b/pi-ask/src/ui/input.ts index 79a3d280..6f2f0637 100644 --- a/pi-ask/src/ui/input.ts +++ b/pi-ask/src/ui/input.ts @@ -19,6 +19,8 @@ export type AskInputCommand = | { kind: "confirm" } | { kind: "cancel" } | { kind: "changeQuestionType" } + | { kind: "skipQuestion" } + | { kind: "cancelWithComment" } | { kind: "dismiss" } | { kind: "later" } | { kind: "showSettings" } @@ -50,7 +52,7 @@ export function getInputCommand( if (state.view.kind === "input") { return getAnswerEditorInputCommand(config, data, editingText); } - if (state.view.kind === "note") { + if (state.view.kind === "note" || state.view.kind === "comment") { return getNoteEditorInputCommand(config, data, editingText); } @@ -159,6 +161,15 @@ function getNavigationInputCommand( return { kind: "openOptionNote" }; } + // Plain keys, so only here: no text editor is open in this view. + if (isSubmitTab(state)) { + if (matchesBinding(data, bindings.cancelComment)) { + return { kind: "cancelWithComment" }; + } + } else if (matchesBinding(data, bindings.skip)) { + return { kind: "skipQuestion" }; + } + if (!isSubmitTab(state)) { return { kind: "ignore" }; } diff --git a/pi-ask/src/ui/render-frame.ts b/pi-ask/src/ui/render-frame.ts index 748f19b9..075c25ff 100644 --- a/pi-ask/src/ui/render-frame.ts +++ b/pi-ask/src/ui/render-frame.ts @@ -72,7 +72,11 @@ function renderTabs(state: AskState, theme: Theme, width: number): string { const tabs = state.questions.map((question, index) => { const active = state.activeTabIndex === index; const answered = isQuestionAnswered(state, question.id); - const marker = answered ? "☒" : "☐"; + const skipped = state.skipped?.includes(question.id) === true; + let marker = answered ? "☒" : "☐"; + if (skipped) { + marker = "⊘"; + } const text = ` ${marker} ${question.label} `; return { text, @@ -209,6 +213,8 @@ function renderFooter( let context: FooterKeymapContext; if (state.view.kind === "input") { context = "input"; + } else if (state.view.kind === "comment") { + context = "comment"; } else if (state.view.kind === "note") { context = "note"; } else if (isSubmitTab(state)) { diff --git a/pi-ask/src/ui/render-question.ts b/pi-ask/src/ui/render-question.ts index bcace34e..405a4aa6 100644 --- a/pi-ask/src/ui/render-question.ts +++ b/pi-ask/src/ui/render-question.ts @@ -22,6 +22,17 @@ export function renderQuestionScreen(context: QuestionRenderContext) { const model = buildQuestionScreenModel(context); pushWrappedText(lines, question.prompt, width, theme, "text", " ", " "); + if (context.state.skipped?.includes(question.id)) { + pushWrappedText( + lines, + UI_TEXT.skippedQuestion, + width, + theme, + "warning", + " ", + " " + ); + } renderQuestionNote(lines, model.questionNote, context); for (const row of model.rows) { diff --git a/pi-ask/src/ui/render-submit.ts b/pi-ask/src/ui/render-submit.ts index bb58a517..f11a7de4 100644 --- a/pi-ask/src/ui/render-submit.ts +++ b/pi-ask/src/ui/render-submit.ts @@ -1,12 +1,13 @@ import { truncateToWidth } from "@earendil-works/pi-tui"; -import { UI_TEXT } from "../constants/ui.ts"; +import { UI_DIMENSIONS, UI_TEXT } from "../constants/ui.ts"; import type { AskState } from "../types.ts"; import { mergeColumns, pushSavedNote, pushWrappedText, + renderEditorBlock, } from "./render-helpers.ts"; -import type { Theme } from "./render-types.ts"; +import type { QuestionRenderContext, Theme } from "./render-types.ts"; import { buildReviewScreenModel } from "./view-models/review.ts"; export function renderSubmitScreen( @@ -14,7 +15,8 @@ export function renderSubmitScreen( state: AskState, theme: Theme, width: number, - reviewShortcutHint?: string + reviewShortcutHint?: string, + editor?: QuestionRenderContext["editor"] ) { const model = buildReviewScreenModel(state, width); if (model.layout === "wide") { @@ -34,6 +36,7 @@ export function renderSubmitScreen( lines.push(line); } appendReviewShortcutHint(lines, reviewShortcutHint, theme, width); + appendCommentEditor(lines, state, editor, theme, width); return; } @@ -43,6 +46,34 @@ export function renderSubmitScreen( lines.push(""); lines.push(...actionLines); appendReviewShortcutHint(lines, reviewShortcutHint, theme, width); + appendCommentEditor(lines, state, editor, theme, width); +} + +/** The reason for cancelling, typed under the review while it is open. */ +function appendCommentEditor( + lines: string[], + state: AskState, + editor: QuestionRenderContext["editor"] | undefined, + theme: Theme, + width: number +) { + if (!editor || state.view.kind !== "comment") { + return; + } + lines.push(""); + pushWrappedText(lines, UI_TEXT.commentTitle, width, theme, "warning", " ", " "); + renderEditorBlock({ + lines, + editorLines: editor.render( + Math.max(UI_DIMENSIONS.editorMinWidth, width - UI_DIMENSIONS.editorContentPadding) + ), + width, + theme, + indent: " ", + availableWidth: width - 1, + placeholder: UI_TEXT.editorPlaceholderComment, + isEmpty: editor.getText().length === 0, + }); } function renderSubmitReviewLines( @@ -71,6 +102,10 @@ function renderReviewQuestion( width: number ) { pushWrappedText(lines, question.label, width, theme, "text", " ", " "); + if (question.skipped) { + lines.push(truncateToWidth(` ${theme.fg("warning", UI_TEXT.skipped)}`, width)); + return; + } if (question.unanswered) { lines.push( truncateToWidth(` ${theme.fg("dim", UI_TEXT.unanswered)}`, width) diff --git a/pi-ask/src/ui/render.ts b/pi-ask/src/ui/render.ts index 213af547..be9d32cf 100644 --- a/pi-ask/src/ui/render.ts +++ b/pi-ask/src/ui/render.ts @@ -56,7 +56,7 @@ export function renderAskScreen(args: { }); if (isSubmitTab(state)) { - renderSubmitScreen(lines, state, theme, width, reviewShortcutHint); + renderSubmitScreen(lines, state, theme, width, reviewShortcutHint, editor); } else if (question) { renderQuestionScreen({ lines, diff --git a/pi-ask/src/ui/view-models/review.ts b/pi-ask/src/ui/view-models/review.ts index d160712e..08b787c3 100644 --- a/pi-ask/src/ui/view-models/review.ts +++ b/pi-ask/src/ui/view-models/review.ts @@ -21,6 +21,8 @@ export interface ReviewQuestionModel { label: string; note?: string; selections?: ReviewSelectionModel[]; + /** Declined on purpose; not the same as unanswered. */ + skipped?: boolean; unanswered: boolean; } @@ -46,10 +48,12 @@ export function buildReviewScreenModel( ? "wide" : "stacked", questions: state.questions.map((question) => - toReviewQuestionModel( - question.label, - toReviewAnswer(question, state.answers[question.id]) - ) + state.skipped?.includes(question.id) + ? { label: question.label, skipped: true, unanswered: false } + : toReviewQuestionModel( + question.label, + toReviewAnswer(question, state.answers[question.id]) + ) ), }; } diff --git a/pi-ask/tests/render-frame.test.ts b/pi-ask/tests/render-frame.test.ts index 58e395fa..59e25680 100644 --- a/pi-ask/tests/render-frame.test.ts +++ b/pi-ask/tests/render-frame.test.ts @@ -228,7 +228,7 @@ test("footer hints wrap into exact lines on narrow screens", () => { assert.deepEqual(lines.slice(-7, -1), [ " Space toggle", "Enter continue", - "N/Shift+N note", + "N/Shift+N note · S skip", "Esc dismiss", "t question type", "? settings", @@ -258,7 +258,7 @@ test("footer keeps earlier hint chunk on the first wrapped line", () => { assert.deepEqual(lines.slice(-6, -1), [ " Enter confirm", "N/Shift+N note", - "Esc dismiss", + "S skip · Esc dismiss", "t question type", "? settings", ]); diff --git a/pi-ask/tests/skip-cancel-flow.test.ts b/pi-ask/tests/skip-cancel-flow.test.ts new file mode 100644 index 00000000..b605e2ff --- /dev/null +++ b/pi-ask/tests/skip-cancel-flow.test.ts @@ -0,0 +1,189 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { registerAskBackground } from "../src/background.ts"; +import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; +import { getAskConfigStore } from "../src/config/store.ts"; +import { createAskRuntime } from "../src/runtime.ts"; +import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; + +const choice = (id: string) => ({ + id, + label: id.toUpperCase(), + prompt: `Pick ${id}?`, + options: [ + { value: "yes", label: "Yes" }, + { value: "no", label: "No" }, + ], +}); +const PARAMS = { title: "Plan", questions: [choice("a"), choice("b")] }; +const TAB = "\t"; + +function boot() { + const host = fakePi(); + const runtime = createAskRuntime(host.pi); + registerAskBackground(host.pi, runtime); + registerAskTool(host.pi, { + runtime, + features: { background: true, expiry: true }, + }); + let calls = 0; + const ask = (params: object = PARAMS) => + host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); + return { ...host, host, ask }; +} + +const typeText = (press: (...keys: string[]) => void, text: string) => + press(...text.split("")); + +beforeEach(quietConfig); + +test("s skips the current question and the result lists it apart from unanswered", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + const form = host.forms[0]; + form?.press("s"); + assert.match(form?.render() ?? "", /⊘ A/, "the tab is marked"); + assert.match(form?.render() ?? "", /Pick b\?/, "moved on to the next question"); + form?.press(TAB); // leave b unanswered + const review = form?.render() ?? ""; + assert.match(review, /→ skipped/); + assert.match(review, /→ unanswered/); + form?.press(KEY.enter); + + const response = await pending; + assert.equal(response.details.status, "submitted"); + assert.deepEqual(response.details.skipped, ["a"]); + assert.deepEqual(response.details.unanswered, ["b"]); + const text = response.content[0].text; + assert.match(text, /A: \(skipped by the user\)/); + assert.match(text, /B: \(no answer\)/); + assert.match(text, /not approval and not an answer/); +}); + +test("skipping every question still needs an explicit submit, even with auto-submit on", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + behaviour: { + ...DEFAULT_ASK_CONFIG.behaviour, + autoSubmitWhenAnsweredWithoutNotes: true, + }, + notifications: { ...DEFAULT_ASK_CONFIG.notifications, enabled: false }, + }); + const host = boot(); + let settled = false; + const pending = host.ask().then((response: any) => { + settled = true; + return response; + }); + await tick(); + host.forms[0]?.press("s", "s"); + await tick(); + assert.equal(settled, false, "waiting on the review tab"); + assert.match(host.forms[0]?.render() ?? "", /Review answers/); + host.forms[0]?.press(KEY.enter); + const response = await pending; + assert.deepEqual(response.details.skipped, ["a", "b"]); + assert.deepEqual(response.details.answers, {}); +}); + +test("the skip key is typed text inside a text editor, not a skip", async () => { + const host = boot(); + const pending = host.ask({ + questions: [{ id: "why", label: "Why", prompt: "Why?", type: "text" }], + }); + await tick(); + typeText(host.forms[0]?.press ?? (() => {}), "sc"); + host.forms[0]?.press(KEY.enter, KEY.enter); + const response = await pending; + assert.equal(response.details.skipped, undefined); + assert.equal(response.details.answers.why.customText, "sc"); +}); + +test("c on the review tab opens a comment; sending it cancels with the reason", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + const form = host.forms[0]; + form?.press(TAB, TAB); + assert.match(form?.render() ?? "", /C cancel with comment/); + form?.press("c"); + const typing = form?.render() ?? ""; + assert.match(typing, /Why are you cancelling/); + assert.match(typing, /Enter cancel with comment/); + typeText(form?.press ?? (() => {}), "wrong repo"); + form?.press(KEY.enter); + + const response = await pending; + assert.equal(response.details.status, "cancelled"); + assert.equal(response.details.comment, "wrong repo"); + const text = response.content[0].text; + assert.match(text, /Reason: "wrong repo"/); + assert.match(text, /Cancellation is not approval; keep risky actions blocked/); + assert.equal(host.journal().at(-1).result.comment, "wrong repo"); +}); + +test("an empty comment, or Esc, goes back to the review without cancelling", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + const form = host.forms[0]; + form?.press(TAB, TAB, "c", KEY.enter); + assert.match(form?.render() ?? "", /Review answers/); + assert.doesNotMatch(form?.render() ?? "", /Why are you cancelling/); + form?.press("c"); + typeText(form?.press ?? (() => {}), "oops"); + form?.press(KEY.escape); + assert.doesNotMatch(form?.render() ?? "", /Why are you cancelling/); + form?.press(KEY.enter); // Submit + assert.equal((await pending).details.status, "submitted"); +}); + +test("cancelling the normal way carries no comment and reads as before", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + host.forms[0]?.press(TAB, TAB, KEY.down, KEY.enter); + const response = await pending; + assert.equal(response.details.status, "cancelled"); + assert.equal("comment" in response.details, false); + assert.equal(response.content[0].text, "User cancelled the ask flow"); +}); + +test("a background form delivers its comment without waking the agent", async () => { + const host = boot(); + host.emit("session_start", { reason: "startup" }); + await tick(); + const receipt = await host.ask({ ...PARAMS, background: true }); + assert.equal(receipt.details.status, "queued"); + assert.ok(host.focusIs("panel")); + host.type(TAB, TAB, "c"); + typeText((...keys) => host.type(...keys), "later please"); + host.type(KEY.enter); + await tick(); + + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.options?.triggerTurn, false, "a cancellation never wakes"); + const content = host.sent[0]?.message.content ?? ""; + assert.match(content, /cancelled/); + assert.match(content, /The user's reason: "later please"\./); + assert.match(content, /Cancellation is not approval/); + assert.equal(host.sent[0]?.message.details.result.comment, "later please"); +}); + +test("a background form delivers skipped questions by id", async () => { + const host = boot(); + host.emit("session_start", { reason: "startup" }); + await tick(); + await host.ask({ ...PARAMS, background: true }); + host.type("s", KEY.enter); + // Question b: pick Yes; then review: submit. + host.type(KEY.enter); + await tick(); + const content = host.sent[0]?.message.content ?? ""; + assert.match(content, /- a "Pick a\?": \(skipped by the user\)/); + assert.match(content, /- b "Pick b\?": Yes \[yes\]/); + assert.match(content, /not approval and not an answer/); + assert.deepEqual(host.sent[0]?.message.details.result.skipped, ["a"]); +}); diff --git a/pi-ask/tests/skip-cancel.test.ts b/pi-ask/tests/skip-cancel.test.ts new file mode 100644 index 00000000..5bbbe79d --- /dev/null +++ b/pi-ask/tests/skip-cancel.test.ts @@ -0,0 +1,248 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { DEFAULT_ASK_CONFIG, normalizeAskConfig } from "../src/config/defaults.ts"; +import { + DEFAULT_ASK_KEYMAPS, + normalizeConfiguredKeymaps, + renderFooterKeymaps, +} from "../src/constants/keymaps.ts"; +import { formatDeliveredOutcome } from "../src/delivery.ts"; +import { renderResultText } from "../src/result.ts"; +import { createInitialState } from "../src/state/create.ts"; +import { + applyDraftSnapshot, + draftContentKey, + toDraftSnapshot, +} from "../src/state/draft.ts"; +import { + saveEditorDraft, + submitEditorDraft, +} from "../src/state/editor.ts"; +import { summarizeResult, toAskResult } from "../src/state/result.ts"; +import { + cancelWithComment, + confirmCurrentSelection, + enterCancelComment, + enterQuestionNoteMode, + MAX_CANCEL_COMMENT_LENGTH, + saveNote, + skipCurrentQuestion, +} from "../src/state/transitions.ts"; +import { getInputCommand } from "../src/ui/input.ts"; +import { buildReviewScreenModel } from "../src/ui/view-models/review.ts"; + +const choice = (id: string) => ({ + id, + label: id.toUpperCase(), + prompt: `Pick ${id}?`, + options: [ + { value: "yes", label: "Yes" }, + { value: "no", label: "No" }, + ], +}); +const PARAMS = { + questions: [choice("a"), choice("b"), choice("c")], +}; +const fresh = () => createInitialState(PARAMS); + +test("skipping drops the answer and notes, moves on, and lists ids in question order", () => { + let state = confirmCurrentSelection(fresh()); // a: Yes, now on b + state = saveNote(enterQuestionNoteMode({ ...state, activeTabIndex: 0 }, "a"), "careful"); + assert.ok(state.answers.a?.note); + state = { ...state, activeTabIndex: 0, view: { kind: "navigate" } }; + + state = skipCurrentQuestion(state); + assert.equal(state.answers.a, undefined, "answer and note are gone"); + assert.deepEqual(state.skipped, ["a"]); + assert.equal(state.activeTabIndex, 1); + assert.equal(state.completed, false, "the form stays open"); + + // Skip c first, then b: the result still lists them in question order. + state = skipCurrentQuestion({ ...state, activeTabIndex: 2 }); + state = skipCurrentQuestion({ ...state, activeTabIndex: 1 }); + assert.deepEqual(state.skipped, ["a", "b", "c"]); +}); + +test("skipping everything still waits on the review tab for an explicit submit", () => { + let state = fresh(); + for (let index = 0; index < 3; index++) { + state = skipCurrentQuestion(state); + } + assert.equal(state.activeTabIndex, 3, "on the review tab"); + assert.equal(state.completed, false); + assert.deepEqual(state.skipped, ["a", "b", "c"]); + // A no-op on the review tab. + assert.equal(skipCurrentQuestion(state), state); +}); + +test("answering a skipped question takes the skip back", () => { + let state = skipCurrentQuestion(fresh()); + assert.deepEqual(state.skipped, ["a"]); + state = confirmCurrentSelection({ ...state, activeTabIndex: 0, view: { kind: "navigate" } }); + assert.deepEqual(state.skipped, []); + assert.equal(toAskResult(state).skipped, undefined); +}); + +test("skipped is its own list: never unanswered, never an answer", () => { + let state = skipCurrentQuestion(fresh()); + state = confirmCurrentSelection(state); // b: Yes + const result = toAskResult(state); + assert.deepEqual(result.skipped, ["a"]); + assert.deepEqual(result.unanswered, ["c"]); + assert.deepEqual(Object.keys(result.answers), ["b"]); + + const text = summarizeResult(result); + assert.match(text, /A: \(skipped by the user\)/); + assert.match(text, /C: \(no answer\)/); + assert.match(text, /The user skipped: A\./); + assert.match(text, /not approval and not an answer/); + assert.match(renderResultText(result), /⊘ A: \(skipped by the user\)/); + + const delivered = formatDeliveredOutcome({ ...result, requestId: "ask-1" }); + assert.match(delivered, /- a "Pick a\?": \(skipped by the user\)/); + assert.match(delivered, /- c "Pick c\?": \(no answer\)/); + assert.match(delivered, /not approval and not an answer/); +}); + +test("a skip survives the journal draft", () => { + const state = skipCurrentQuestion(fresh()); + const draft = toDraftSnapshot(state); + assert.deepEqual(draft.skipped, ["a"]); + assert.notEqual(draftContentKey(draft), draftContentKey(toDraftSnapshot(fresh()))); + const restored = applyDraftSnapshot(fresh(), draft); + assert.deepEqual(restored.skipped, ["a"]); + assert.deepEqual( + applyDraftSnapshot(fresh(), { ...draft, skipped: ["zzz"] }).skipped, + undefined + ); +}); + +test("the review model marks a skipped question apart from an unanswered one", () => { + const state = skipCurrentQuestion(fresh()); + const [a, b] = buildReviewScreenModel(state, 80).questions; + assert.equal(a?.skipped, true); + assert.equal(a?.unanswered, false); + assert.equal(b?.skipped, undefined); + assert.equal(b?.unanswered, true); +}); + +// --- Cancel with a comment ------------------------------------------------- + +const onReview = () => ({ ...fresh(), activeTabIndex: 3, view: { kind: "submit" as const } }); + +test("a comment is typed on the review tab and cancels only when sent", () => { + assert.equal(enterCancelComment(fresh()).view.kind, "navigate", "not outside the review tab"); + const typing = enterCancelComment(onReview()); + assert.equal(typing.view.kind, "comment"); + + const cancelled = submitEditorDraft(typing, " not now, wrong repo "); + assert.equal(cancelled.cancelled, true); + assert.equal(cancelled.completed, true); + assert.equal(cancelled.cancelComment, "not now, wrong repo"); + + const result = toAskResult(cancelled); + assert.equal(result.status, "cancelled"); + assert.equal(result.comment, "not now, wrong repo"); + const text = summarizeResult(result); + assert.match(text, /User cancelled the ask flow\. Reason: "not now, wrong repo"\./); + assert.match(text, /Cancellation is not approval; keep risky actions blocked/); + assert.match(renderResultText(result), /^Cancelled: not now, wrong repo/); + assert.match( + formatDeliveredOutcome({ ...result, requestId: "ask-1" }), + /The user's reason: "not now, wrong repo"\./ + ); +}); + +test("an empty comment or closing the editor cancels nothing", () => { + const typing = enterCancelComment(onReview()); + assert.equal(submitEditorDraft(typing, " ").completed, false); + assert.equal(submitEditorDraft(typing, " ").view.kind, "submit"); + const closed = saveEditorDraft(typing, "half a thought"); + assert.equal(closed.view.kind, "submit"); + assert.equal(closed.cancelComment, undefined); +}); + +test("an uncommented cancel behaves exactly as before", () => { + const cancelled = confirmCurrentSelection({ ...onReview(), activeSubmitActionIndex: 1 }); + const result = toAskResult(cancelled); + assert.equal(result.status, "cancelled"); + assert.equal("comment" in result, false); + assert.equal(summarizeResult(result), "User cancelled the ask flow"); + assert.equal(renderResultText(result), "Cancelled"); +}); + +test("a comment is kept short", () => { + const state = cancelWithComment(onReview(), "x".repeat(2000)); + assert.equal(state.cancelComment?.length, MAX_CANCEL_COMMENT_LENGTH); +}); + +test("a comment never rides on a submitted result", () => { + const state = { ...fresh(), cancelComment: "stale" }; + assert.equal(toAskResult(state).comment, undefined); +}); + +// --- Keys ------------------------------------------------------------------ + +test("skip and comment keys have defaults that collide with nothing", () => { + assert.deepEqual(DEFAULT_ASK_KEYMAPS.main.skip, ["s"]); + assert.deepEqual(DEFAULT_ASK_KEYMAPS.main.cancelComment, ["c"]); + const result = normalizeConfiguredKeymaps(DEFAULT_ASK_KEYMAPS); + assert.ok(result.ok); +}); + +test("skip fires on a question and comment on the review tab, never in an editor", () => { + const nav = getInputCommand(fresh(), DEFAULT_ASK_CONFIG, "s"); + assert.deepEqual(nav, { kind: "skipQuestion" }); + assert.deepEqual(getInputCommand(fresh(), DEFAULT_ASK_CONFIG, "c"), { kind: "ignore" }); + assert.deepEqual(getInputCommand(onReview(), DEFAULT_ASK_CONFIG, "s"), { kind: "ignore" }); + assert.deepEqual(getInputCommand(onReview(), DEFAULT_ASK_CONFIG, "c"), { + kind: "cancelWithComment", + }); + + // A text editor (custom answer, note, comment) receives the letters. + const editing = { + ...fresh(), + view: { kind: "input" as const, questionId: "a" }, + }; + for (const view of [ + editing.view, + { kind: "note" as const, questionId: "a" }, + { kind: "comment" as const }, + ]) { + for (const key of ["s", "c"]) { + assert.deepEqual( + getInputCommand({ ...editing, view }, DEFAULT_ASK_CONFIG, key, "text"), + { kind: "delegateToEditor" } + ); + assert.deepEqual( + getInputCommand({ ...editing, view }, DEFAULT_ASK_CONFIG, key, ""), + { kind: "delegateToEditor" } + ); + } + } +}); + +test("the keys are configurable, old configs gain them, and a bound key is not stolen", () => { + const old = structuredClone(DEFAULT_ASK_KEYMAPS) as any; + delete old.main.skip; + delete old.main.cancelComment; + old.main.optionNote = ["s"]; + const config = normalizeAskConfig({ keymaps: old }); + assert.deepEqual(config.keymaps.main.skip, [], "left unbound, not stolen"); + assert.deepEqual(config.keymaps.main.cancelComment, ["c"]); + + const custom = structuredClone(DEFAULT_ASK_KEYMAPS); + custom.main.skip = ["ctrl+k"]; + assert.deepEqual( + getInputCommand(fresh(), { ...DEFAULT_ASK_CONFIG, keymaps: normalizeAskConfig({ keymaps: custom }).keymaps }, "\u000b"), + { kind: "skipQuestion" } + ); +}); + +test("footer hints offer skip on questions and the comment on the review tab", () => { + assert.match(renderFooterKeymaps(DEFAULT_ASK_CONFIG, "default"), /S skip/); + assert.match(renderFooterKeymaps(DEFAULT_ASK_CONFIG, "multi"), /S skip/); + assert.match(renderFooterKeymaps(DEFAULT_ASK_CONFIG, "submit"), /C cancel with comment/); + assert.match(renderFooterKeymaps(DEFAULT_ASK_CONFIG, "comment"), /Enter cancel with comment · Esc back/); + assert.doesNotMatch(renderFooterKeymaps(DEFAULT_ASK_CONFIG, "input"), /skip/); +}); diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts index 65b76338..993dbeac 100644 --- a/pi-ask/tests/support/fake-pi.ts +++ b/pi-ask/tests/support/fake-pi.ts @@ -92,6 +92,7 @@ export function fakePi( }; let focus: FakeComponent | null = editor; const tui = { + terminal: { rows: 40, columns: 80 }, requestRender() {}, getFocusedComponent: () => focus, setFocus(component: FakeComponent | null) { diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 7adecd63..071f5c54 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,7 +2,7 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "expiry-flow.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled"], }, From 6756036d46439492a632101db5549240e782adb5 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 01:10:51 +0000 Subject: [PATCH 18/38] docs(ask): describe skip and cancel with a comment --- pi-ask/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/pi-ask/README.md b/pi-ask/README.md index 67f58055..881f76c6 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -33,6 +33,8 @@ The agent calls `ask_user`. `/answer` if it asked in prose instead. | Understand a choice first | Notes | | The question is the wrong shape | `t` switches `single` ↔ `multi` | | Answer later | `Ctrl+L` on a blocking form. The agent carries on; the form waits in the panel | +| Decline one question | `s` on that question. Its answer and notes are dropped; the rest of the form carries on | +| Say why you are cancelling | `c` on the review tab, type a short reason, `Enter`. `Esc` goes back without cancelling | ### Questions that do not block @@ -51,6 +53,14 @@ A background question, a form you deferred, and a form left open when Pi last st Both keys are `keymaps.global.later` and `keymaps.global.panelFocus` in the config file. +### Skip and cancel with a comment + +**Skip** declines a single question without cancelling the form. The tab and the review mark it as skipped (not "unanswered"), the result lists `skipped: id[]` in question order, and the result text says a skip is neither an answer nor approval. Answering a skipped question takes the skip back. Skipping every question still ends on the review tab: nothing is sent until you submit, whatever `autoSubmitWhenAnsweredWithoutNotes` says. The key is plain `s`, so it only works where no text editor is open. A text question opens its editor at once; press `Esc` first to skip it. + +**Cancel with a comment** attaches a short reason (500 characters at most) to a cancellation. The `cancelled` result carries `comment`, and the text gives the agent your reason while still saying cancellation is not approval. An empty comment cancels nothing. Cancelling without a comment behaves as it always did. For a background form the comment is delivered with the cancellation, which still never wakes the agent. + +Both keys are `keymaps.main.skip` and `keymaps.main.cancelComment` in the config file; a config written before they existed gains them, unless you already bound that key to something else. + ### Questions that expire An agent that expects you to be away can give a call `timeoutSeconds` and mark one option per question as its `fallback`. If you do not respond in time, the form resolves as `expired`: declared fallbacks are applied and the rest stay unanswered. A fallback is the agent's own assumption, never your approval; the result says so and keeps irreversible or risky actions blocked. @@ -98,6 +108,8 @@ Output: - `requestId`: ties a receipt to the answer delivered later - `pending`: forms waiting, this one included (`queued` only) - `expired: id[]`: answers that are auto-applied fallbacks +- `skipped: id[]`: questions the user declined one by one, in question order. Not unanswered, not approval +- `comment`: why the user cancelled, when they said (`cancelled` only) `queued` (background call) and `deferred` (you chose "answer later") are receipts, not answers. `expired` means nobody responded: a fallback is the agent's assumption, never approval. The rules ride in those results, so they cost context only when they happen. From f9167edcf85651c31373fa6ee9ff33d92200dc7f Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:13:28 +0000 Subject: [PATCH 19/38] fix(ask): retry a wake that never started --- pi-ask/src/background.ts | 13 ++++++++++ pi-ask/src/delivery.ts | 37 ++++++++++++++++++++++++++++ pi-ask/tests/background.test.ts | 43 +++++++++++++++++++++++++++++++++ pi-ask/tests/support/fake-pi.ts | 11 +++++++++ scripts/packages.mjs | 2 +- 5 files changed, 105 insertions(+), 1 deletion(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 45e23bb1..89e56c7e 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -110,6 +110,8 @@ export interface AskBackground { reopen(ctx: ExtensionContext): void; /** The agent run is over; `aborted` when the user stopped it. */ settled(ctx: ExtensionContext, aborted?: boolean): void; + /** A run started: sends that never reached the branch are retried. */ + started(ctx: ExtensionContext): void; } export function registerAskBackground( @@ -122,6 +124,7 @@ export function registerAskBackground( pi.on("session_start", (_event, ctx) => background.attach(ctx)); pi.on("session_tree", (_event, ctx) => background.attach(ctx)); pi.on("session_shutdown", () => background.dispose()); + pi.on("agent_start", (_event, ctx) => background.started(ctx)); pi.on("turn_end", (event, ctx) => background.boundary(ctx, event) as never); pi.on( "agent_before_settle", @@ -615,6 +618,16 @@ export function createAskBackground( // A stale context: the next event tries again. } }, + started(next) { + if (disposed) { + return; + } + try { + delivery.started(next); + } catch { + // A stale context: the next event tries again. + } + }, dispose() { if (disposed) { return; diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 2203af94..462adf9b 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -56,6 +56,11 @@ export interface AskDelivery { ): AskBoundaryResult | undefined; /** An outcome was just journalled with channel `message`. */ post(): void; + /** + * A run started. A send the branch still lacks never made it into a run, + * so the answer is no longer held back; the next pump retries it. + */ + started(ctx: DeliveryContext): void; /** Deliver what can be delivered now. `settled`: the run is over. */ pump( ctx: DeliveryContext, @@ -204,11 +209,43 @@ export function createAskDelivery( } } + /** + * Forgets sends the branch still shows as pending. Pi's `sendMessage` is + * fire-and-forget: when the run it starts fails before recording the + * message, nothing lands and nothing reports the failure. Left in flight, + * that answer would be held for the rest of the process. Only called when + * no run can still be writing the message (the host is idle, or a run just + * started): the branch itself is the proof of what was delivered. + */ + function release(ctx: DeliveryContext) { + if (inFlight.size === 0) { + return; + } + const pending = new Set( + undeliveredOutcomes(readAskJournal(ctx)).map( + ({ outcome }) => outcome.outcomeId + ) + ); + for (const outcomeId of [...inFlight]) { + if (pending.has(outcomeId)) { + inFlight.delete(outcomeId); + } + } + } + return { post() { watching = true; }, + started(ctx) { + // A run that did start has not recorded its own starting message + // yet, so do not send here: the next boundary sees it on the branch. + release(ctx); + }, pump(ctx, situation = {}) { + if (ctx.isIdle()) { + release(ctx); + } const planned = plan(ctx, { trigger: situation.trigger ?? "now", aborted: situation.aborted, diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index f5bd6b35..cde9b97b 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -449,6 +449,49 @@ test("no duplicate when the woken run reaches its turn boundary before the messa assert.equal(host.answers().length, 1); }); +test("a wake whose run never starts is retried instead of losing the answer", async () => { + const { host, requestId } = await withBackgroundForm(); + host.failNextWake(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); + assert.equal(host.isIdle(), true, "the run failed to start"); + + // The host reports the run settled: the branch still lacks the answer, so + // the in-flight send was never delivered and must be offered again. + host.settle(); + await tick(); + assert.equal(host.sent.length, 2); + assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); + assert.equal(host.sent[1]?.message.details.requestId, requestId); + + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); + assert.equal(host.sent.length, 2); +}); + +test("a new run releases an answer whose wake never started, and delivers it once", async () => { + const { host, requestId } = await withBackgroundForm(); + host.failNextWake(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + + // Another run starts. The answer joins it at its first turn boundary. + host.setIdle(false); + host.emit("agent_start"); + const boundary = host.turnEnd(); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.entries[0].details.requestId, requestId); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1); + assert.equal(host.sent.length, 1, "no second wake was needed"); +}); + test("a working agent gets the answer at the next turn boundary, once, with no extra turn started", async () => { const { host, requestId } = await withBackgroundForm(); host.setIdle(false); diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts index 993dbeac..39b25bdb 100644 --- a/pi-ask/tests/support/fake-pi.ts +++ b/pi-ask/tests/support/fake-pi.ts @@ -81,6 +81,9 @@ export function fakePi( const wakes: SentMessage["message"][] = []; const heldCustom: SentMessage["message"][] = []; let idle = true; + // The next triggered send is accepted but its run fails to start before + // recording the message, as a failed pre-run compaction would. + let failWake = false; let aborts = 0; const editor: FakeComponent & { text: string } = { @@ -144,6 +147,10 @@ export function fakePi( sent.push({ message, options: sendOptions }); if (sendOptions?.triggerTurn) { if (idle) { + if (failWake) { + failWake = false; + return; + } idle = false; wakes.push(message); } else { @@ -264,6 +271,10 @@ export function fakePi( setIdle(value: boolean) { idle = value; }, + /** The next triggered send never reaches a run, so it is not recorded. */ + failNextWake() { + failWake = true; + }, isIdle: () => idle, /** Dispatch a lifecycle event; returns what the handlers returned. */ emit, diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 071f5c54..18e08c58 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -4,7 +4,7 @@ export const packages = { name: "@gagansd/pi-ask", tests: "tests", integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], - hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled"], + hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled", "agent_start"], }, "pi-automode": { name: "@gagansd/pi-automode", tests: "tests", From 527e5ffb20bb5d9ed93fb9d8693b96343e0be6c8 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:15:12 +0000 Subject: [PATCH 20/38] fix(ask): deliver an answer whose tool result never landed --- pi-ask/src/background.ts | 2 +- pi-ask/src/delivery.ts | 17 +++++++++- pi-ask/src/journal/replay.ts | 34 ++++++++++++++++++-- pi-ask/tests/background.test.ts | 50 ++++++++++++++++++++++++++++- pi-ask/tests/journal-replay.test.ts | 29 +++++++++++++++++ pi-ask/tests/support/fake-pi.ts | 32 ++++++++++++++++-- 6 files changed, 155 insertions(+), 9 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 89e56c7e..04cf36e0 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -530,7 +530,7 @@ export function createAskBackground( return; } refresh((queue, hidden) => ({ type: "sync", queue, hidden })); - delivery.post(); + delivery.attach(); poke(next); }, poke, diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 462adf9b..1e33cea7 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -56,6 +56,11 @@ export interface AskDelivery { ): AskBoundaryResult | undefined; /** An outcome was just journalled with channel `message`. */ post(): void; + /** + * The branch was (re)built. A foreground answer whose tool result never + * landed is adopted as a follow-up message, once. + */ + attach(): void; /** * A run started. A send the branch still lacks never made it into a run, * so the answer is no longer held back; the next pump retries it. @@ -173,12 +178,18 @@ export function createAskDelivery( // False while the branch is known to have nothing pending, so that turn // boundaries of an ordinary run cost nothing. let watching = true; + // The next plan was reached by rebuilding a session, where a foreground + // answer without its tool result can be adopted as a message. + let recovering = false; function plan(ctx: DeliveryContext, situation: AskDeliverySituation) { if (!watching) { return; } - const pending = undeliveredOutcomes(readAskJournal(ctx)); + const pending = undeliveredOutcomes(readAskJournal(ctx), { + unrecordedTool: recovering, + }); + recovering = false; if (pending.length === 0) { watching = false; return; @@ -237,6 +248,10 @@ export function createAskDelivery( post() { watching = true; }, + attach() { + watching = true; + recovering = true; + }, started(ctx) { // A run that did start has not recorded its own starting message // yet, so do not send here: the next boundary sees it on the branch. diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts index d27aa130..c52c049a 100644 --- a/pi-ask/src/journal/replay.ts +++ b/pi-ask/src/journal/replay.ts @@ -45,6 +45,11 @@ export interface AskJournalRecord { * went on without it. */ supersededByMessage: boolean; + /** + * Pi recorded the tool result for this foreground call. False means the + * process may have died between journalling the answer and the result. + */ + toolResultOnBranch: boolean; toolCallId?: string; } @@ -65,6 +70,17 @@ export function replayJournal( const records = new Map(); const deliveredOutcomeIds = new Map(); let panelHidden = false; + const toolResults = new Set(); + for (const entry of entries) { + if ( + entry.type === "message" && + isRecord(entry.message) && + entry.message.role === "toolResult" && + typeof entry.message.toolCallId === "string" + ) { + toolResults.add(entry.message.toolCallId); + } + } for (const entry of entries) { if (entry.type === "custom_message") { @@ -100,6 +116,9 @@ export function replayJournal( mode: journalEntry.mode === "background" ? "background" : "foreground", form: journalEntry.form, toolCallId: journalEntry.toolCallId, + toolResultOnBranch: + !!journalEntry.toolCallId && + toolResults.has(journalEntry.toolCallId), deferred: false, clockStopped: false, offerDismissed: false, @@ -223,13 +242,22 @@ export function reopenableForms( /** Records whose latest outcome still has to be sent as a follow-up. */ export function undeliveredOutcomes( - state: AskJournalState + state: AskJournalState, + options: { unrecordedTool?: boolean } = {} ): Array { return state.records.filter( (record): record is AskJournalRecord & { outcome: AskOutcomeEntry } => !!record.outcome && - record.outcome.channel === "message" && - !record.delivered.has(record.outcome.outcomeId) + !record.delivered.has(record.outcome.outcomeId) && + (record.outcome.channel === "message" || + // A foreground call's answer is its tool result. If the branch has + // no result for the call, the process died before Pi wrote it, so + // the answer is only in the journal and must be sent instead. This + // is only safe on a rebuild: a live call may still be writing it. + (options.unrecordedTool === true && + record.outcome.channel === "tool" && + !!record.toolCallId && + !record.toolResultOnBranch)) ); } diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index cde9b97b..c16e8f66 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -35,7 +35,11 @@ const SUBMIT_ONE = [KEY.enter, KEY.enter]; /** One Pi process: the extension wired as `src/index.ts` wires it. */ function boot( session?: SessionManager, - options: { background?: boolean; mode?: string } = {} + options: { + background?: boolean; + mode?: string; + persistToolResults?: boolean; + } = {} ) { const host = fakePi(session, options); const runtime = createAskRuntime(host.pi); @@ -614,6 +618,50 @@ test("an outcome journalled but never recorded is delivered on the next start, o assert.equal(host.sent.length, 1); }); +test("an answer whose tool result never reached the branch is delivered on attach", async () => { + // The process died after the outcome was journalled but before Pi wrote + // the tool result: the branch has the answer, the agent never saw it. + const dying = boot(undefined, { persistToolResults: false }); + const pending = dying.ask(); + await tick(); + dying.forms[0]?.press(...SUBMIT_TWO); + const response = await pending; + assert.equal(response.details.status, "submitted"); + assert.equal(dying.answers().length, 0); + assert.equal(dying.journal().at(-1)?.channel, "tool"); + + const host = boot(dying.session); + await start(host, "resume"); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, response.details.requestId); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: true }); + + host.recordWake(); + await start(host, "reload"); + assert.equal(host.sent.length, 1, "the answer message proves delivery"); + assert.equal(host.answers().length, 1); +}); + +test("a tool result on the branch proves the answer was delivered", async () => { + const dying = boot(undefined, { persistToolResults: false }); + const pending = dying.ask(); + await tick(); + dying.forms[0]?.press(...SUBMIT_TWO); + await pending; + dying.session.appendMessage({ + role: "toolResult", + toolCallId: "call-1", + toolName: "ask_user", + content: [{ type: "text", text: "answered" }], + isError: false, + timestamp: Date.now(), + }); + + const host = boot(dying.session); + await start(host, "resume"); + assert.deepEqual(host.sent, []); +}); + test("a cancellation is recorded as context and never wakes or aborts the agent", async () => { const { host, requestId } = await withBackgroundForm(); // Dismiss, confirmed because the form has a draft. diff --git a/pi-ask/tests/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts index 374be54b..99ab8648 100644 --- a/pi-ask/tests/journal-replay.test.ts +++ b/pi-ask/tests/journal-replay.test.ts @@ -110,6 +110,35 @@ test("a tool outcome completes the form and needs no delivery", () => { assert.deepEqual(interruptedForms(state), []); assert.deepEqual(undeliveredOutcomes(state), []); assert.equal(getRecord(state, requestId)?.outcome?.result.status, "submitted"); + assert.equal(getRecord(state, requestId)?.toolResultOnBranch, false); +}); + +test("a tool outcome whose tool result never landed is recovered as a message", () => { + const b = branch(); + const requestId = b.form(); + b.journal.recordOutcome(requestId, result(), "tool"); + const state = replayJournal(b.entries); + + // Only a rebuild may adopt it: a live call could still write the result. + assert.deepEqual(undeliveredOutcomes(state), []); + assert.deepEqual( + undeliveredOutcomes(state, { unrecordedTool: true }).map( + (record) => record.requestId + ), + [requestId] + ); + + // The tool result on the branch proves the answer was delivered. + b.entries.push({ + type: "message", + message: { role: "toolResult", toolCallId: "call-1" }, + }); + const withResult = replayJournal(b.entries); + assert.equal(getRecord(withResult, requestId)?.toolResultOnBranch, true); + assert.deepEqual( + undeliveredOutcomes(withResult, { unrecordedTool: true }), + [] + ); }); test("a message outcome stays undelivered until its marker is written", () => { diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts index 39b25bdb..df5954bf 100644 --- a/pi-ask/tests/support/fake-pi.ts +++ b/pi-ask/tests/support/fake-pi.ts @@ -63,7 +63,12 @@ export function quietConfig() { /** One extension runtime ("process") attached to a session. */ export function fakePi( session: SessionManager = SessionManager.inMemory(), - options: { mode?: string; persistSentMessages?: boolean } = {} + options: { + mode?: string; + /** Model a process that dies before Pi records a tool result. */ + persistToolResults?: boolean; + persistSentMessages?: boolean; + } = {} ) { const handlers = new Map unknown>>(); const tools: any[] = []; @@ -80,6 +85,7 @@ export function fakePi( // Messages the host has accepted but not yet written to the session. const wakes: SentMessage["message"][] = []; const heldCustom: SentMessage["message"][] = []; + const persistToolResults = options.persistToolResults ?? true; let idle = true; // The next triggered send is accepted but its run fails to start before // recording the message, as a failed pre-run compaction would. @@ -131,8 +137,28 @@ export function fakePi( handlers.set(event, [...(handlers.get(event) ?? []), handler]); return () => {}; }, - registerTool(tool: unknown) { - tools.push(tool); + registerTool(tool: any) { + const run = tool.execute; + tools.push({ + ...tool, + async execute(...args: any[]) { + const result = await run(...args); + if (persistToolResults) { + session.appendMessage({ + role: "toolResult", + toolCallId: String(args[0]), + toolName: tool.name, + content: result.content ?? [], + ...(result.details === undefined + ? {} + : { details: result.details }), + isError: false, + timestamp: Date.now(), + }); + } + return result; + }, + }); }, registerCommand(name: string, command: unknown) { commands.set(name, command); From 583eeb6ea3c9c7c345c8b0c9bc2d39ae71b5f510 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:15:35 +0000 Subject: [PATCH 21/38] docs(ask): report the default token footprint --- pi-ask/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pi-ask/README.md b/pi-ask/README.md index 881f76c6..3ed7e504 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -133,13 +133,13 @@ Schema settings apply on `/reload`, not live. A disabled field is absent from th Recurring model-facing contribution of `ask_user`, measured with `npm run tokens` (character proxy: `ceil(chars / 4)`, not provider billing): -| Part | Chars | Est. tokens | +| Part | Default, all enabled (chars / tokens) | Expiry off (chars / tokens) | | --- | ---: | ---: | -| description | 148 | 37 | -| prompt snippet | 103 | 26 | -| prompt guidelines | 723 | 181 | -| parameter schema | 560 | 140 | -| **total** | **1,534** | **384** | +| description | 148 / 37 | 148 / 37 | +| prompt snippet | 103 / 26 | 103 / 26 | +| prompt guidelines | 723 / 181 | 723 / 181 | +| parameter schema | 624 / 156 | 560 / 140 | +| **total** | **1,598 / 400** | **1,534 / 384** | Field-level prose lives in the guidelines; the registered schema ships without `description` keys. From 3a95ae9aa3e9dd9673ae7d38de7ff0bc42861cbb Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:16:12 +0000 Subject: [PATCH 22/38] fix(ask): arm the expiry clock only after a notification succeeds --- pi-ask/src/notifications.ts | 11 +++++++++++ pi-ask/src/ui/controller.ts | 21 ++++++++++++++------- pi-ask/tests/expiry-flow.test.ts | 20 ++++++++++++++++++++ 3 files changed, 45 insertions(+), 7 deletions(-) diff --git a/pi-ask/src/notifications.ts b/pi-ask/src/notifications.ts index ddefd7b9..089d2822 100644 --- a/pi-ask/src/notifications.ts +++ b/pi-ask/src/notifications.ts @@ -23,6 +23,17 @@ export interface NotificationAttempt { status: NotificationAttemptStatus; } +/** + * Whether the user was told. A disabled notification or an inert channel + * counts as success: nothing failed. Only a failed channel leaves the + * expiry clock unarmed. + */ +export function notificationSucceeded( + attempts: readonly NotificationAttempt[] +): boolean { + return attempts.every((attempt) => attempt.status !== "failed"); +} + export function createQuestionWaitingNotification( question: Pick ): AskNotificationPayload { diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index ea292131..76e6d8f4 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -4,6 +4,8 @@ import type { AskConfig } from "../config/schema.ts"; import { getAskConfigStore } from "../config/store.ts"; import { createQuestionWaitingNotification, + type NotificationAttempt, + notificationSucceeded, notifyQuestionWaiting, } from "../notifications.ts"; import type { AskDraftSnapshot } from "../journal/entries.ts"; @@ -209,11 +211,16 @@ export function createAskFlowController( syncSelection(controller); const unsubscribeExpiry = bindExpiry(controller, params.expiry?.owned === true); notifyCurrentQuestion(controller) - .catch(() => { - // Notification failures are best-effort and must not affect the ask flow. + .then((attempts) => { + // The clock starts only after the user has been told a question waits. + if (notificationSucceeded(attempts)) { + controller.expiry?.arm(); + } }) - // The clock starts only after the user has been told a question waits. - .then(() => controller.expiry?.arm()); + .catch(() => { + // Notification failures are best-effort and leave the clock unarmed: + // nobody was told, so the form waits like one behind another. + }); return { get focused() { @@ -686,12 +693,12 @@ function refresh(controller: AskFlowController) { async function notifyCurrentQuestion( controller: AskFlowController -): Promise { +): Promise { const question = getCurrentQuestion(controller.state); if (!question) { - return; + return []; } - await notifyQuestionWaiting( + return notifyQuestionWaiting( controller.config, createQuestionWaitingNotification(question) ); diff --git a/pi-ask/tests/expiry-flow.test.ts b/pi-ask/tests/expiry-flow.test.ts index dfca946a..6496536b 100644 --- a/pi-ask/tests/expiry-flow.test.ts +++ b/pi-ask/tests/expiry-flow.test.ts @@ -177,6 +177,26 @@ test("the clock waits for the notification before it starts", async () => { assert.equal(host.time.pending, 1); }); +test("a failed notification leaves the clock unarmed", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { + channels: [{ command: "pi-ask-missing-notify", type: "command" }], + enabled: true, + }, + }); + const host = boot(); + host.ask(TIMED).catch(() => {}); + // Let the command notification fail; the user was never told. + await new Promise((resolve) => setTimeout(resolve, 200)); + assert.equal( + host.time.pending, + 0, + "a form nobody was told about must not count down" + ); + assert.equal(host.forms.length, 1); +}); + test("a question with no declared fallback expires with nothing applied", async () => { const host = boot(); const pending = host.ask({ ...PLAIN, timeoutSeconds: 30 }); From a36487b47ee56fe8d4910c63bea7dfff8ac39131 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:18:29 +0000 Subject: [PATCH 23/38] refactor(ask): drop the unused delivery marker and honour the stopped clock --- pi-ask/src/background.ts | 5 ++++- pi-ask/src/journal/entries.ts | 19 ++----------------- pi-ask/src/journal/journal.ts | 9 --------- pi-ask/src/journal/replay.ts | 3 --- pi-ask/tests/expiry-flow.test.ts | 20 +++++++++++++++++++- pi-ask/tests/journal-replay.test.ts | 16 ++++++---------- 6 files changed, 31 insertions(+), 41 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 04cf36e0..7d594511 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -266,7 +266,10 @@ export function createAskBackground( function syncTimers() { const view = panelView(state); for (const [requestId, timer] of timers) { - if (view.visible && view.formId === requestId) { + // A stop the journal recorded is final, even if a timer somehow + // survived the rebuild that read it. + const stopped = records.get(requestId)?.clockStopped === true; + if (!stopped && view.visible && view.formId === requestId) { timer.show(); } else { timer.hide(); diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts index 55aac535..b6466180 100644 --- a/pi-ask/src/journal/entries.ts +++ b/pi-ask/src/journal/entries.ts @@ -23,8 +23,8 @@ export type AskFormMode = "foreground" | "background"; /** * How an outcome reaches the agent. `tool`: it was the tool call's own result. - * `message`: the tool call is gone (or returned a receipt), so the outcome - * must be sent as a follow-up message and tracked with a `delivered` entry. + * `message`: the tool call is gone (or returned a receipt), so the outcome is + * sent as a follow-up; the `pi-ask:answer` message on the branch proves it. */ export type AskOutcomeChannel = "tool" | "message"; @@ -88,15 +88,6 @@ export interface AskOutcomeEntry extends AskJournalEntryBase { supersedes?: string; } -/** - * Exactly-once marker for a `message` outcome. Independent of queue state: - * it names the outcome, so a correction to an expired form is a new delivery. - */ -export interface AskDeliveredEntry extends AskJournalEntryBase { - kind: "delivered"; - outcomeId: string; -} - /** * The user put the background panel away (`hidden: true`) or brought it * back. Latest wins; `requestId` is the form that was showing, if any. @@ -131,7 +122,6 @@ export type AskJournalEntry = | AskDraftEntry | AskDeferEntry | AskOutcomeEntry - | AskDeliveredEntry | AskPanelEntry | AskExpiryEntry | AskDismissEntry; @@ -150,7 +140,6 @@ const ENTRY_KINDS = new Set([ "draft", "defer", "outcome", - "delivered", "panel", "expiry", "dismiss", @@ -182,10 +171,6 @@ export function parseJournalEntry(data: unknown): AskJournalEntry | undefined { return typeof data.outcomeId === "string" && isRecord(data.result) ? (data as unknown as AskOutcomeEntry) : undefined; - case "delivered": - return typeof data.outcomeId === "string" - ? (data as unknown as AskDeliveredEntry) - : undefined; case "panel": return typeof data.hidden === "boolean" ? (data as unknown as AskPanelEntry) diff --git a/pi-ask/src/journal/journal.ts b/pi-ask/src/journal/journal.ts index 00773c7c..05933354 100644 --- a/pi-ask/src/journal/journal.ts +++ b/pi-ask/src/journal/journal.ts @@ -31,12 +31,6 @@ export interface AskJournal { requestId: string, initial?: AskDraftSnapshot ): (state: AskState) => void; - /** - * Marks a `message` outcome as having reached the agent. Delivery does - * not write it: the answer message on the branch is the proof. Replay - * still honours it for a host that confirms delivery some other way. - */ - recordDelivered(requestId: string, outcomeId: string): void; /** A foreground form moved to the queue ("answer later"). */ recordDefer(requestId: string): void; /** The user closed an expired form without correcting it. */ @@ -133,9 +127,6 @@ export function createAskJournal( recordExpiryStop(requestId, reason) { write({ kind: "expiry", requestId, reason }); }, - recordDelivered(requestId, outcomeId) { - write({ kind: "delivered", requestId, outcomeId }); - }, }; } diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts index c52c049a..44161d9f 100644 --- a/pi-ask/src/journal/replay.ts +++ b/pi-ask/src/journal/replay.ts @@ -151,9 +151,6 @@ export function replayJournal( case "dismiss": record.offerDismissed = true; break; - case "delivered": - deliveredOutcomeIds.set(journalEntry.outcomeId, journalEntry.requestId); - break; default: break; } diff --git a/pi-ask/tests/expiry-flow.test.ts b/pi-ask/tests/expiry-flow.test.ts index 6496536b..3da75890 100644 --- a/pi-ask/tests/expiry-flow.test.ts +++ b/pi-ask/tests/expiry-flow.test.ts @@ -54,7 +54,7 @@ function boot( const ask = (params: object) => host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); const askInBackground = (params: object) => ask({ ...params, background: true }); - return { ...host, host, time, ask, askInBackground }; + return { ...host, host, time, runtime, ask, askInBackground }; } type Host = ReturnType; @@ -197,6 +197,24 @@ test("a failed notification leaves the clock unarmed", async () => { assert.equal(host.forms.length, 1); }); +test("a stop recorded in the journal is never given back to a live timer", async () => { + const host = boot(); + await start(host); + const receipt = await host.askInBackground(TIMED); + await tick(); + assert.equal(host.time.pending, 1); + + // The stop was journalled without this process stopping its timer, e.g. + // by a rebuild that read another process's entry. + host.runtime.journal.recordExpiryStop( + receipt.details.requestId, + "interaction" + ); + host.emit("session_tree"); + await tick(); + assert.equal(host.time.pending, 0, "a stopped countdown stays stopped"); +}); + test("a question with no declared fallback expires with nothing applied", async () => { const host = boot(); const pending = host.ask({ ...PLAIN, timeoutSeconds: 30 }); diff --git a/pi-ask/tests/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts index 99ab8648..bfa12a88 100644 --- a/pi-ask/tests/journal-replay.test.ts +++ b/pi-ask/tests/journal-replay.test.ts @@ -141,7 +141,7 @@ test("a tool outcome whose tool result never landed is recovered as a message", ); }); -test("a message outcome stays undelivered until its marker is written", () => { +test("a message outcome stays undelivered until its answer is on the branch", () => { const b = branch(); const requestId = b.form(); const outcome = b.journal.recordOutcome(requestId, result(), "message"); @@ -150,14 +150,6 @@ test("a message outcome stays undelivered until its marker is written", () => { [requestId] ); - b.journal.recordDelivered(requestId, outcome.outcomeId); - assert.deepEqual(undeliveredOutcomes(replayJournal(b.entries)), []); -}); - -test("a persisted answer message proves delivery without a marker", () => { - const b = branch(); - const requestId = b.form(); - const outcome = b.journal.recordOutcome(requestId, result(), "message"); b.entries.push({ type: "custom_message", customType: ASK_ANSWER_MESSAGE_TYPE, @@ -174,7 +166,11 @@ test("delivery is tracked per outcome, so a late correction is delivered again", result("expired"), "message" ); - b.journal.recordDelivered(requestId, expired.outcomeId); + b.entries.push({ + type: "custom_message", + customType: ASK_ANSWER_MESSAGE_TYPE, + details: { requestId, outcomeId: expired.outcomeId }, + }); let state = replayJournal(b.entries); assert.deepEqual(undeliveredOutcomes(state), []); assert.deepEqual( From b00b8d41cfca3a4d3cadeee7e65541a69986ebb2 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:18:51 +0000 Subject: [PATCH 24/38] docs(ask): describe the async release in the changelog --- pi-ask/CHANGELOG.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/pi-ask/CHANGELOG.md b/pi-ask/CHANGELOG.md index 7b2a8605..67da1621 100644 --- a/pi-ask/CHANGELOG.md +++ b/pi-ask/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## Unreleased + +`ask_user` can now ask in the background, take an answer later, and time out safely. + +- **Background questions.** `background: true` queues the form and returns a `queued` receipt with a `requestId`, so the agent keeps working. The answer arrives as a `pi-ask:answer` message at the next turn boundary, or wakes an idle agent. A cancellation is added as context but never starts a turn. +- **Answer later.** `Ctrl+L` on a blocking form returns `deferred` and moves the form, draft intact, to a panel above the input. `Alt+A` moves the keyboard between panel and input; `Esc` or `Ctrl+L` hides it; a line under the input counts waiting forms. `/ask-panel` reopens it. +- **Expiry with fallback.** A call can set `timeoutSeconds` and each question an optional `fallback` option `value`. On by default with a 30-second floor. The countdown runs only while the form is on screen, after the notification fires; any key, hiding or deferring stops it for good. On lapse the form resolves `expired` with only declared fallbacks applied, and the result says a fallback is the agent's assumption, not approval. +- **Late override.** An expired form stays reopenable for an hour through `/ask-panel`; submitting sends one correction that replaces the timed-out result. Dismissing it without a comment leaves the earlier result standing. +- **Session journal and recovery.** Forms, drafts, panel state, countdown stops and outcomes are saved in the session. An interrupted form reopens on startup, resume or fork with its draft. Delivery stays exactly-once across reload, resume, compaction and branch moves: the `pi-ask:answer` message on the active branch is the proof, and a wake whose run never started is retried. +- **Cancel with a comment and skip.** `c` on the review tab attaches a short reason to a cancellation. `s` declines one question without cancelling the form; skipped is neither an answer nor approval. +- **Configuration and keys.** New keys `behaviour.background`, `expiry.enabled` and `expiry.minSeconds`, plus keymaps `global.later`, `global.panelFocus`, `main.skip` and `main.cancelComment`. `/ask-settings` exposes the expiry toggles; schema changes apply on `/reload`. `/ask-panel` shows waiting and expired forms. +- **Hosts without the custom TUI** keep the blocking card flow: `background` blocks there and there is no countdown. +- The default `ask_user` context footprint is 1,598 tokens, or 1,534 with expiry off, within the existing 450/420 ceilings. + ## 0.1.5 - Add RPC dialog interviews with single/multi-select, free-text answers, back navigation, and review before submission. From 6bf1f08371df25f5ddaafd2a1cfcbd46419fbab1 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:39:29 +0000 Subject: [PATCH 25/38] fix(ask): retry an adopted answer whose wake never starts A tool-channel answer adopted on a rebuild stayed in flight when its wake run failed to start, so it was held until the next reload or fork. Count adopted tool outcomes when releasing sends the branch lacks, and re-arm the adoption when such a send is dropped, so the next plan retries it in the same process. Keep the adoption armed after a plan that could only hold the outcome. Delivery stays exactly-once: the branch message or tool result remains the only proof. --- pi-ask/src/delivery.ts | 26 ++++++++++++++++------ pi-ask/tests/background.test.ts | 38 +++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 6 deletions(-) diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 1e33cea7..2c52fe9a 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -189,7 +189,11 @@ export function createAskDelivery( const pending = undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: recovering, }); - recovering = false; + // Only a plan that can act on an adopted answer clears the adoption. One + // that can only hold it leaves the next plan able to adopt and send it. + if (situation.trigger !== "now" || situation.idle) { + recovering = false; + } if (pending.length === 0) { watching = false; return; @@ -232,14 +236,24 @@ export function createAskDelivery( if (inFlight.size === 0) { return; } - const pending = new Set( - undeliveredOutcomes(readAskJournal(ctx)).map( - ({ outcome }) => outcome.outcomeId + // An adopted tool outcome counts here too: neither call site has a live + // call that could still be writing its result, so the branch proves it + // was never sent. + const pending = new Map( + undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true }).map( + ({ outcome }) => [outcome.outcomeId, outcome] ) ); for (const outcomeId of [...inFlight]) { - if (pending.has(outcomeId)) { - inFlight.delete(outcomeId); + const outcome = pending.get(outcomeId); + if (!outcome) { + continue; + } + inFlight.delete(outcomeId); + // The adopted answer never reached the branch, so adopt it again and + // let the next plan retry it in this process. + if (outcome.channel === "tool") { + recovering = true; } } } diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index c16e8f66..4cfa4358 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -88,6 +88,21 @@ async function withBackgroundForm(params: object = PARAMS) { return { host, receipt, requestId: receipt.details.requestId as string }; } +/** + * A session whose blocking form was answered, but where Pi died before it + * wrote the tool result: the answer exists only in the journal. + */ +async function unrecordedToolSession() { + const first = boot(undefined, { persistToolResults: false }); + const pending = first.ask(); + await tick(); + first.forms[0]?.press(...SUBMIT_TWO); + await pending; + assert.equal(first.journal().at(-1)?.channel, "tool"); + assert.equal(first.answers().length, 0); + return first.session; +} + beforeEach(quietConfig); // --- The tool call --------------------------------------------------------- @@ -477,6 +492,29 @@ test("a wake whose run never starts is retried instead of losing the answer", as assert.equal(host.sent.length, 2); }); +test("an adopted tool answer whose wake never starts is retried here, once", async () => { + const session = await unrecordedToolSession(); + const host = boot(session, { persistToolResults: false }); + host.failNextWake(); + await start(host); + assert.equal(host.sent.length, 1, "the rebuild adopts the answer as a wake"); + assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); + assert.equal(host.isIdle(), true, "the run failed to start"); + + // The branch still lacks the adopted answer, so it must be offered again + // in this process instead of waiting for the next reload or fork. + host.settle(); + await tick(); + assert.equal(host.sent.length, 2, "the failed adoption is retried"); + assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); + + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); + assert.equal(host.sent.length, 2); +}); + test("a new run releases an answer whose wake never started, and delivers it once", async () => { const { host, requestId } = await withBackgroundForm(); host.failNextWake(); From 11e9a65fb795e71059b0624e512bd5c52904eb2d Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 03:39:30 +0000 Subject: [PATCH 26/38] docs(ask): cite token estimates in the changelog footprint The 1,598 and 1,534 figures are characters; the token estimates are 400 and 384, which is what the 450/420 ceilings are denominated in. --- pi-ask/CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pi-ask/CHANGELOG.md b/pi-ask/CHANGELOG.md index 67da1621..3c043db8 100644 --- a/pi-ask/CHANGELOG.md +++ b/pi-ask/CHANGELOG.md @@ -12,7 +12,7 @@ - **Cancel with a comment and skip.** `c` on the review tab attaches a short reason to a cancellation. `s` declines one question without cancelling the form; skipped is neither an answer nor approval. - **Configuration and keys.** New keys `behaviour.background`, `expiry.enabled` and `expiry.minSeconds`, plus keymaps `global.later`, `global.panelFocus`, `main.skip` and `main.cancelComment`. `/ask-settings` exposes the expiry toggles; schema changes apply on `/reload`. `/ask-panel` shows waiting and expired forms. - **Hosts without the custom TUI** keep the blocking card flow: `background` blocks there and there is no countdown. -- The default `ask_user` context footprint is 1,598 tokens, or 1,534 with expiry off, within the existing 450/420 ceilings. +- The default `ask_user` context footprint is 1,598 chars (≈ 400 tokens), or 1,534 (≈ 384) with expiry off, within the existing 450/420 token ceilings. ## 0.1.5 From 0301a15d155e14e1d2887b25d3c965f25969e0d3 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 22:50:32 +0000 Subject: [PATCH 27/38] fix(ask): keep editor text in recovered drafts The journal now records the form with the open editor's text folded in, so a custom answer or note typed but not yet submitted survives a restart. Keystrokes are reported after a short pause and flushed on any other state change, answer later and dispose. --- pi-ask/CHANGELOG.md | 2 +- pi-ask/src/ui/controller.ts | 77 ++++++++++++++++++++++++++++----- pi-ask/tests/background.test.ts | 61 +++++++++++++++++++++++++- 3 files changed, 126 insertions(+), 14 deletions(-) diff --git a/pi-ask/CHANGELOG.md b/pi-ask/CHANGELOG.md index 3c043db8..98c58fbb 100644 --- a/pi-ask/CHANGELOG.md +++ b/pi-ask/CHANGELOG.md @@ -8,7 +8,7 @@ - **Answer later.** `Ctrl+L` on a blocking form returns `deferred` and moves the form, draft intact, to a panel above the input. `Alt+A` moves the keyboard between panel and input; `Esc` or `Ctrl+L` hides it; a line under the input counts waiting forms. `/ask-panel` reopens it. - **Expiry with fallback.** A call can set `timeoutSeconds` and each question an optional `fallback` option `value`. On by default with a 30-second floor. The countdown runs only while the form is on screen, after the notification fires; any key, hiding or deferring stops it for good. On lapse the form resolves `expired` with only declared fallbacks applied, and the result says a fallback is the agent's assumption, not approval. - **Late override.** An expired form stays reopenable for an hour through `/ask-panel`; submitting sends one correction that replaces the timed-out result. Dismissing it without a comment leaves the earlier result standing. -- **Session journal and recovery.** Forms, drafts, panel state, countdown stops and outcomes are saved in the session. An interrupted form reopens on startup, resume or fork with its draft. Delivery stays exactly-once across reload, resume, compaction and branch moves: the `pi-ask:answer` message on the active branch is the proof, and a wake whose run never started is retried. +- **Session journal and recovery.** Forms, drafts (including text typed in an editor and not yet submitted), panel state, countdown stops and outcomes are saved in the session. An interrupted form reopens on startup, resume or fork with its draft. Delivery stays exactly-once across reload, resume, compaction and branch moves: the `pi-ask:answer` message on the active branch is the proof, and a wake whose run never started is retried. - **Cancel with a comment and skip.** `c` on the review tab attaches a short reason to a cancellation. `s` declines one question without cancelling the form; skipped is neither an answer nor approval. - **Configuration and keys.** New keys `behaviour.background`, `expiry.enabled` and `expiry.minSeconds`, plus keymaps `global.later`, `global.panelFocus`, `main.skip` and `main.cancelComment`. `/ask-settings` exposes the expiry toggles; schema changes apply on `/reload`. `/ask-panel` shows waiting and expired forms. - **Hosts without the custom TUI** keep the blocking card flow: `background` blocks there and there is no countdown. diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 76e6d8f4..09c0740c 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -104,6 +104,7 @@ export interface AskFlowOptions { /** The form as a TUI component, for hosts other than `ctx.ui.custom`. */ export interface AskFlowComponent { + /** Closes the form. Typed text not yet reported is reported first. */ dispose(): void; focused: boolean; /** The live form state, including unsaved editor text. */ @@ -122,10 +123,14 @@ interface AskFlowController { done: Done; editor: Editor; expiry?: ExpiryTimer; + /** Set once the form has its result; nothing is journalled after that. */ + finished: boolean; focused: boolean; onInput?: (data: string) => void; onStateChange?: (state: AskState) => void; panel?: { onHide: () => void }; + /** Trailing timer for draft reports made while the user types. */ + pendingDraftTimer?: ReturnType; pendingDiscardConfirm: boolean; pendingQuestionTypeChangeQuestionId?: string; pendingReviewShortcutActionIndex?: number; @@ -138,6 +143,9 @@ interface AskFlowController { unsubscribeConfig: () => void; } +/** Typing is reported to the journal after this much quiet. */ +export const DRAFT_TYPING_DEBOUNCE_MS = 750; + export async function runAskFlow( ctx: ExtensionContext, params: AskParams, @@ -175,9 +183,13 @@ export function createAskFlowController( config: params.config, configNotice: params.configNotice, ctx: params.ctx, - done, + done: (result) => { + controller.finished = true; + done(result); + }, editor: createEditor(tui, theme, params.cwd), expiry: params.expiry?.timer, + finished: false, focused: false, onInput: params.onInput, onStateChange: params.onStateChange, @@ -230,10 +242,7 @@ export function createAskFlowController( controller.focused = value; controller.editor.focused = value; }, - getState: () => - isEditingView(controller.state) - ? saveEditorDraft(controller.state, controller.editor.getText()) - : controller.state, + getState: () => snapshotState(controller), render: (width: number) => renderController(controller, width), invalidate() { controller.editor.invalidate(); @@ -245,12 +254,49 @@ export function createAskFlowController( handleControllerInput(controller, data); }, dispose() { + flushDraft(controller); unsubscribeExpiry(); controller.unsubscribeConfig(); }, }; } +/** The state with the open editor's text folded in; the live state stays. */ +function snapshotState(controller: AskFlowController): AskState { + return isEditingView(controller.state) + ? saveEditorDraft(controller.state, controller.editor.getText()) + : controller.state; +} + +function cancelDraftTimer(controller: AskFlowController) { + if (controller.pendingDraftTimer !== undefined) { + clearTimeout(controller.pendingDraftTimer); + controller.pendingDraftTimer = undefined; + } +} + +/** Reports the current draft now, including unsent editor text. */ +function flushDraft(controller: AskFlowController) { + cancelDraftTimer(controller); + if (!controller.finished) { + controller.onStateChange?.(snapshotState(controller)); + } +} + +/** Keystrokes in an editor are reported once typing pauses, not one by one. */ +function scheduleDraft(controller: AskFlowController) { + if (!controller.onStateChange) { + return; + } + cancelDraftTimer(controller); + const timer = setTimeout(() => { + controller.pendingDraftTimer = undefined; + flushDraft(controller); + }, DRAFT_TYPING_DEBOUNCE_MS); + timer.unref?.(); + controller.pendingDraftTimer = timer; +} + /** Redraws on each tick; a form that owns its clock also finishes on expiry. */ function bindExpiry(controller: AskFlowController, owned: boolean) { const timer = controller.expiry; @@ -356,7 +402,7 @@ function handleEditingCommand( } if (command.kind === "delegateToEditor") { controller.editor.handleInput(data); - refresh(controller); + refresh(controller, { typing: true }); } } @@ -558,10 +604,9 @@ function answerLater(controller: AskFlowController) { return; } // The draft keeps typed text; the open editor itself is left as it is. - const saved = isEditingView(controller.state) - ? saveEditorDraft(controller.state, controller.editor.getText()) - : controller.state; + const saved = snapshotState(controller); controller.pendingDiscardConfirm = false; + cancelDraftTimer(controller); controller.onStateChange?.(saved); if (controller.panel) { controller.tui.requestRender(); @@ -685,9 +730,17 @@ function showSettingsModal(controller: AskFlowController) { }); } -function refresh(controller: AskFlowController) { - // Every state change ends in a refresh, so this is the one observation point. - controller.onStateChange?.(controller.state); +function refresh( + controller: AskFlowController, + options: { typing?: boolean } = {} +) { + // Every state change ends in a refresh, so this is the one observation + // point. Unsaved editor text is part of what it reports. + if (options.typing) { + scheduleDraft(controller); + } else { + flushDraft(controller); + } controller.tui.requestRender(); } diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index 4cfa4358..4409dc6d 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -1,5 +1,5 @@ import assert from "node:assert/strict"; -import test, { beforeEach } from "node:test"; +import test, { beforeEach, mock } from "node:test"; import { SessionManager } from "@earendil-works/pi-coding-agent"; import { registerAskTool } from "../src/ask-tool.ts"; import { registerAskBackground } from "../src/background.ts"; @@ -878,3 +878,62 @@ test("the queue is TUI-only and a torn-down runtime writes nothing", async () => assert.deepEqual(kinds(host), ["form", "draft"]); assert.equal(host.turnEnd().entries.length, 0); }); + +const TEXT_FORM = { + title: "Notes", + questions: [{ id: "dir", label: "DIR", prompt: "Which directory?", type: "text" }], +}; + +test("text typed in an editor survives a restart, written once typing pauses", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + assert.ok(host.focusIs("panel"), "a new form takes the idle keyboard"); + + mock.timers.enable({ apis: ["setTimeout"] }); + try { + host.type(..."src/ui"); + assert.deepEqual(kinds(host), ["form"], "keystrokes are not written one by one"); + mock.timers.tick(5000); + } finally { + mock.timers.reset(); + } + assert.deepEqual(kinds(host), ["form", "draft"], "one draft for the burst"); + + // A key that ends the typing writes at once, with the text folded in. + host.type("/"); + host.type(KEY.escape); + assert.deepEqual(kinds(host), ["form", "draft", "draft"]); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /src\/ui\//, "the unfinished answer came back"); +}); + +test("an editor still open when Pi quits is journalled on dispose", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + host.type(..."draft text"); + assert.deepEqual(kinds(host), ["form"]); + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), ["form", "draft"]); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /draft text/); +}); + +test("a tree move to the same branch keeps the form, with its unsent text", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + host.type(..."keep"); + host.emit("session_tree"); + await tick(); + assert.match(host.panelText(), /keep/); + host.type(KEY.focus, ..."me"); + assert.match(host.panelText(), /keepme/); +}); From 44eb6aabd8a207438b90ce599264076095c09d9c Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 22:50:55 +0000 Subject: [PATCH 28/38] fix(ask): rebuild a retained form after a tree move Moving the session tree now compares the loaded panel form with the new branch's draft and rebuilds it, and its draft recorder, when they differ, so answers rolled back on the old branch are neither shown nor submitted. Focus and expiry clocks are left alone. --- pi-ask/src/background.ts | 37 ++++++++++++++++++++++++++++++++- pi-ask/src/ui/controller.ts | 10 +++++++++ pi-ask/src/ui/panel.ts | 14 +++++++++++++ pi-ask/tests/background.test.ts | 26 +++++++++++++++++++++++ 4 files changed, 86 insertions(+), 1 deletion(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 7d594511..791cd3c1 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -39,7 +39,11 @@ import { } from "./journal/replay.ts"; import type { AskRuntime } from "./runtime.ts"; import { createInitialState } from "./state/create.ts"; -import { applyDraftSnapshot } from "./state/draft.ts"; +import { + applyDraftSnapshot, + draftContentKey, + toDraftSnapshot, +} from "./state/draft.ts"; import { createExpiryTimer, type ExpiryTimer, @@ -159,6 +163,9 @@ export function createAskBackground( deps.newTimer ?? ((seconds) => createExpiryTimer(seconds, clock)); const delivery = createAskDelivery(pi); const recorders = new Map void>(); + // Content key of the draft each loaded form last started from or wrote, + // to tell whether a re-read branch still agrees with what is on screen. + const shown = new Map(); // Countdowns of background forms created in THIS process. A form from an // earlier process (restart, resume, fork, reload) never has one: the user // had no fair chance to see its clock, so it waits like a normal form. @@ -207,6 +214,7 @@ export function createAskBackground( return; } recorderFor(requestId)(formState); + shown.set(requestId, draftContentKey(toDraftSnapshot(formState))); updateIndicator(); }, }); @@ -257,6 +265,31 @@ export function createAskBackground( }; } + /** + * The session moved (resume, tree jump): the journal of the new branch + * is the truth. A form kept on screen from the old branch is rebuilt from + * it when its draft differs, so answers rolled back are not shown or sent. + */ + function reconcileBranch(current: ExtensionContext) { + try { + recorders.clear(); + readQueue(current); + for (const requestId of [...shown.keys()]) { + const record = records.get(requestId); + const branchKey = record + ? draftContentKey(record.draft ?? { answers: {} }) + : undefined; + if (branchKey === shown.get(requestId)) { + continue; + } + shown.delete(requestId); + panel.drop(requestId); + } + } catch { + // A stale context: the next lifecycle event rebuilds. + } + } + function releaseTimer(requestId: string, timer = timers.get(requestId)) { timer?.dispose(); timers.delete(requestId); @@ -347,6 +380,7 @@ export function createAskBackground( ctx.ui.notify(askStrings().recoveredNotice, "info"); } const expired = record.outcome?.result.status === "expired"; + shown.set(requestId, draftContentKey(record.draft ?? { answers: {} })); return { requestId, config, @@ -532,6 +566,7 @@ export function createAskBackground( if (!adopt(next)) { return; } + reconcileBranch(next); refresh((queue, hidden) => ({ type: "sync", queue, hidden })); delivery.attach(); poke(next); diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 09c0740c..f7fd05ea 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -104,6 +104,11 @@ export interface AskFlowOptions { /** The form as a TUI component, for hosts other than `ctx.ui.custom`. */ export interface AskFlowComponent { + /** + * Drops the form like `dispose` but without reporting the unsent editor + * text: the form belongs to a branch the session has left. + */ + detach(): void; /** Closes the form. Typed text not yet reported is reported first. */ dispose(): void; focused: boolean; @@ -253,6 +258,11 @@ export function createAskFlowController( controller.onInput?.(data); handleControllerInput(controller, data); }, + detach() { + cancelDraftTimer(controller); + controller.onStateChange = undefined; + this.dispose(); + }, dispose() { flushDraft(controller); unsubscribeExpiry(); diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts index bbc3d88f..cd29a325 100644 --- a/pi-ask/src/ui/panel.ts +++ b/pi-ask/src/ui/panel.ts @@ -65,6 +65,11 @@ export interface AskPanel { ): boolean; /** Drop the loaded form without telling anyone; nothing more is called. */ discard(): void; + /** + * Drop the loaded form if it is `requestId`, keeping the widget and the + * keyboard where they are. Its unsent text is not reported. + */ + drop(requestId: string): boolean; /** Drop the loaded form unless it is one of `requestIds`. */ retain(requestIds: readonly string[]): void; /** The loaded form's live state, including unsaved editor text. */ @@ -227,6 +232,15 @@ export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { unmount(); unloadForm(); }, + drop(requestId) { + if (form?.requestId !== requestId) { + return false; + } + const loaded = form; + form = undefined; + loaded.component.detach(); + return true; + }, retain(requestIds) { if (form && !requestIds.includes(form.requestId)) { unloadForm(); diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index 4409dc6d..b1b5a685 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -926,6 +926,32 @@ test("an editor still open when Pi quits is journalled on dispose", async () => assert.match(later.panelText(), /draft text/); }); +test("a tree move rebuilds a kept form from the branch, dropping rolled-back answers", async () => { + const session = SessionManager.inMemory(); + session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + const formEntry = session.getBranch().at(-1)?.id; + assert.ok(formEntry); + host.type(KEY.enter); + assert.match(host.panelText(), /Which cache\?/, "DB answered, cache is next"); + assert.deepEqual(kinds(host), ["form", "draft"]); + + // Back to the moment the form was asked: the answer is not on this branch. + session.branch(formEntry); + host.emit("session_tree"); + await tick(); + assert.deepEqual(kinds(host), ["form"]); + assert.match(host.panelText(), /Which database\?/, "the rolled-back answer is gone"); + assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); + + host.type(KEY.focus, ...SUBMIT_TWO); + await tick(); + assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); +}); + test("a tree move to the same branch keeps the form, with its unsent text", async () => { const host = boot(); await start(host, "startup"); From 2ca22ca3cc3f909ced944ffc223cdd83be1631bc Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 22:55:52 +0000 Subject: [PATCH 29/38] fix(ask): do not renotify a form rebuilt after a tree move --- pi-ask/src/background.ts | 5 +++++ pi-ask/src/ui/controller.ts | 30 +++++++++++++++++++----------- pi-ask/src/ui/panel.ts | 3 +++ pi-ask/tests/background.test.ts | 31 +++++++++++++++++++++++++++++++ 4 files changed, 58 insertions(+), 11 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 791cd3c1..df0d28a5 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -166,6 +166,8 @@ export function createAskBackground( // Content key of the draft each loaded form last started from or wrote, // to tell whether a re-read branch still agrees with what is on screen. const shown = new Map(); + // Forms put on screen at least once here: their user was already told. + const seen = new Set(); // Countdowns of background forms created in THIS process. A form from an // earlier process (restart, resume, fork, reload) never has one: the user // had no fair chance to see its clock, so it waits like a normal form. @@ -381,7 +383,10 @@ export function createAskBackground( } const expired = record.outcome?.result.status === "expired"; shown.set(requestId, draftContentKey(record.draft ?? { answers: {} })); + const rebuilt = seen.has(requestId); + seen.add(requestId); return { + rebuilt, requestId, config, draft: record.draft, diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index f7fd05ea..912ff8f6 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -100,6 +100,12 @@ export interface AskFlowOptions { * cancelled with the dismiss key or from the review tab. */ panel?: { onHide: () => void }; + /** + * The user was already told about this form in this process; it is only + * being rebuilt. No second notification, and the clock is left to the + * first build, whose notification arms the shared timer once it succeeds. + */ + rebuilt?: boolean; } /** The form as a TUI component, for hosts other than `ctx.ui.custom`. */ @@ -227,17 +233,19 @@ export function createAskFlowController( controller.editor.onSubmit = (value) => submitEditor(controller, value); syncSelection(controller); const unsubscribeExpiry = bindExpiry(controller, params.expiry?.owned === true); - notifyCurrentQuestion(controller) - .then((attempts) => { - // The clock starts only after the user has been told a question waits. - if (notificationSucceeded(attempts)) { - controller.expiry?.arm(); - } - }) - .catch(() => { - // Notification failures are best-effort and leave the clock unarmed: - // nobody was told, so the form waits like one behind another. - }); + if (params.rebuilt !== true) { + notifyCurrentQuestion(controller) + .then((attempts) => { + // The clock starts only after the user has been told a question waits. + if (notificationSucceeded(attempts)) { + controller.expiry?.arm(); + } + }) + .catch(() => { + // Notification failures are best-effort and leave the clock unarmed: + // nobody was told, so the form waits like one behind another. + }); + } return { get focused() { diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts index cd29a325..6a91452f 100644 --- a/pi-ask/src/ui/panel.ts +++ b/pi-ask/src/ui/panel.ts @@ -35,6 +35,8 @@ export interface AskPanelForm { /** Counts down while this form is on screen; see `state/expiry.ts`. */ expiry?: ExpiryTimer; params: AskParams; + /** Shown before in this process: built again, e.g. after a tree move. */ + rebuilt?: boolean; requestId: string; } @@ -275,6 +277,7 @@ function createPanelForm( onInput: (data) => callbacks.onInput?.(requestId, data), onStateChange: (state) => callbacks.onStateChange(requestId, state), panel: { onHide: () => callbacks.onHide(requestId) }, + rebuilt: form.rebuilt, } ); } diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index b1b5a685..b4ec5f3a 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -3,6 +3,8 @@ import test, { beforeEach, mock } from "node:test"; import { SessionManager } from "@earendil-works/pi-coding-agent"; import { registerAskTool } from "../src/ask-tool.ts"; import { registerAskBackground } from "../src/background.ts"; +import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; +import { getAskConfigStore } from "../src/config/store.ts"; import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; import { createAskRuntime } from "../src/runtime.ts"; import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; @@ -963,3 +965,32 @@ test("a tree move to the same branch keeps the form, with its unsent text", asyn host.type(KEY.focus, ..."me"); assert.match(host.panelText(), /keepme/); }); + +test("a form rebuilt after a tree move does not notify the user again", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { channels: ["bell"], enabled: true }, + }); + const bells = () => writes.mock.calls.filter((call) => call.arguments[0] === "\x07").length; + const writes = mock.method(process.stdout, "write", () => true); + try { + const session = SessionManager.inMemory(); + session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + await tick(); + assert.equal(bells(), 1, "the user is told once, when the form first appears"); + const formEntry = session.getBranch().at(-1)?.id; + assert.ok(formEntry); + host.type(KEY.enter); + + session.branch(formEntry); + host.emit("session_tree"); + await tick(); + assert.match(host.panelText(), /Which database\?/, "the form was rebuilt"); + assert.equal(bells(), 1, "a rebuilt form is not announced again"); + } finally { + writes.mock.restore(); + } +}); From ad985355de8d00ccf8409454776aff2119c9da37 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Tue, 17 Nov 2026 22:58:32 +0000 Subject: [PATCH 30/38] fix(ask): flush a blocking form's draft on shutdown --- pi-ask/src/ask-tool.ts | 6 +++++- pi-ask/src/background.ts | 10 ++++++++- pi-ask/src/runtime.ts | 7 +++++++ pi-ask/src/ui/controller.ts | 12 +++++++++++ pi-ask/tests/background.test.ts | 37 +++++++++++++++++++++++++++++++++ 5 files changed, 70 insertions(+), 2 deletions(-) diff --git a/pi-ask/src/ask-tool.ts b/pi-ask/src/ask-tool.ts index 2839d38d..90e250c6 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -62,7 +62,7 @@ export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {}) } async function executeAskTool( - { background, clock, journal, live }: AskRuntime, + { background, clock, flushers, journal, live }: AskRuntime, features: AskFeatures, toolCallId: string, params: AskParams, @@ -131,6 +131,10 @@ async function executeAskTool( allowDefer: !!background, expiry: timer && { owned: true, timer }, onStateChange: journal.draftRecorder(requestId), + registerFlush: (flush) => { + flushers.add(flush); + return () => flushers.delete(flush); + }, }); let result: AskResult; ctx.ui.setWorkingVisible(false); diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index df0d28a5..22d7c964 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -154,7 +154,7 @@ export function registerAskBackground( export function createAskBackground( pi: Pick, - { clock, journal, live }: AskRuntime, + { clock, flushers, journal, live }: AskRuntime, deps: AskBackgroundDeps = {} ): AskBackground { const defer = deps.defer ?? ((task) => setTimeout(task, 0)); @@ -675,6 +675,14 @@ export function createAskBackground( if (disposed) { return; } + // Blocking forms are not in the panel: report their typing first. + for (const flush of [...flushers]) { + try { + flush(); + } catch { + // The journal is gone; nothing more can be kept. + } + } try { panel.discard(); ctx?.ui.setWidget(ASK_PENDING_WIDGET_KEY, undefined); diff --git a/pi-ask/src/runtime.ts b/pi-ask/src/runtime.ts index 1f622786..879bb8b0 100644 --- a/pi-ask/src/runtime.ts +++ b/pi-ask/src/runtime.ts @@ -12,6 +12,12 @@ export interface AskRuntime { * only the tool is registered: every call then blocks. */ background?: AskBackground; + /** + * Reports the pending draft of each blocking form on screen. Run when + * the extension shuts down: a form's typing timer must not decide whether + * the last keystrokes are kept. + */ + flushers: Set<() => void>; journal: AskJournal; /** * Request ids whose blocking form is on screen in this process. The queue @@ -26,6 +32,7 @@ export function createAskRuntime( ): AskRuntime { return { clock, + flushers: new Set(), journal: createSessionAskJournal(pi, clock && { now: clock.now }), live: new Set(), }; diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 912ff8f6..50a72d30 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -106,6 +106,11 @@ export interface AskFlowOptions { * first build, whose notification arms the shared timer once it succeeds. */ rebuilt?: boolean; + /** + * Hands the host a way to report the pending draft now (shutdown), and + * gets back a call that withdraws it when the form is over. + */ + registerFlush?: (flush: () => void) => () => void; } /** The form as a TUI component, for hosts other than `ctx.ui.custom`. */ @@ -188,6 +193,9 @@ export function createAskFlowController( ], params: AskFlowParams ): AskFlowComponent { + let unregisterFlush = () => { + // replaced once the controller exists + }; const controller: AskFlowController = { allowDefer: params.allowDefer === true, banner: params.banner, @@ -196,6 +204,7 @@ export function createAskFlowController( ctx: params.ctx, done: (result) => { controller.finished = true; + unregisterFlush(); done(result); }, editor: createEditor(tui, theme, params.cwd), @@ -230,6 +239,8 @@ export function createAskFlowController( maybeFinish(controller); }); + unregisterFlush = + params.registerFlush?.(() => flushDraft(controller)) ?? unregisterFlush; controller.editor.onSubmit = (value) => submitEditor(controller, value); syncSelection(controller); const unsubscribeExpiry = bindExpiry(controller, params.expiry?.owned === true); @@ -273,6 +284,7 @@ export function createAskFlowController( }, dispose() { flushDraft(controller); + unregisterFlush(); unsubscribeExpiry(); controller.unsubscribeConfig(); }, diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index b4ec5f3a..23567bfd 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -994,3 +994,40 @@ test("a form rebuilt after a tree move does not notify the user again", async () writes.mock.restore(); } }); + +test("a blocking form's last keystrokes are journalled on shutdown", async () => { + const host = boot(); + await start(host, "startup"); + const pending = host.ask(TEXT_FORM); + pending.catch(() => {}); + await tick(); + mock.timers.enable({ apis: ["setTimeout"] }); + try { + host.forms[0]?.press(..."src/ui"); + assert.deepEqual(kinds(host), ["form"], "typing waits for the pause"); + // Pi quits before the typing timer fires. + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), ["form", "draft"]); + mock.timers.tick(5000); + } finally { + mock.timers.reset(); + } + assert.deepEqual(kinds(host), ["form", "draft"], "nothing is written twice"); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /src\/ui/, "the unfinished answer came back"); +}); + +test("a finished blocking form is not flushed again on shutdown", async () => { + const host = boot(); + await start(host, "startup"); + const pending = host.ask(PARAMS); + await tick(); + host.forms[0]?.press(...SUBMIT_TWO); + await pending; + const before = kinds(host); + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), before); +}); From f31c17a0212a6b19f81dc1bb2807592d32a4359b Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 00:50:09 +0000 Subject: [PATCH 31/38] test(ask): split background coverage by lifecycle responsibility --- pi-ask/tests/background-delivery.test.ts | 354 +++++++++ pi-ask/tests/background-panel.test.ts | 191 +++++ pi-ask/tests/background-recovery.test.ts | 283 +++++++ pi-ask/tests/background.test.ts | 895 +---------------------- pi-ask/tests/support/background.ts | 102 +++ scripts/packages.mjs | 2 +- 6 files changed, 941 insertions(+), 886 deletions(-) create mode 100644 pi-ask/tests/background-delivery.test.ts create mode 100644 pi-ask/tests/background-panel.test.ts create mode 100644 pi-ask/tests/background-recovery.test.ts create mode 100644 pi-ask/tests/support/background.ts diff --git a/pi-ask/tests/background-delivery.test.ts b/pi-ask/tests/background-delivery.test.ts new file mode 100644 index 00000000..a0982dc6 --- /dev/null +++ b/pi-ask/tests/background-delivery.test.ts @@ -0,0 +1,354 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; +import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; +import { + boot, + start, + kinds, + ONE, + SUBMIT_TWO, + withBackgroundForm, + unrecordedToolSession, +} from "./support/background.ts"; + +beforeEach(quietConfig); + +// --- Delivery -------------------------------------------------------------- + +test("an idle agent is woken by the answer, which names the form and each question", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + + assert.equal(host.sent.length, 1); + const [{ message, options }] = host.sent; + assert.equal(message.customType, ASK_ANSWER_MESSAGE_TYPE); + assert.deepEqual(options, { triggerTurn: true }); + assert.equal( + message.content, + [ + `User answered your earlier ask_user form ${requestId} (Storage):`, + '- db "Which database?": Postgres [postgres]', + '- cache "Which cache?": Redis [redis]', + ].join("\n") + ); + assert.equal(message.details.result.status, "submitted"); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); + assert.equal(host.journal().at(-1).channel, "message"); +}); + +test("no duplicate when the woken run reaches its turn boundary before the message is recorded", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 0, "the run has not recorded it yet"); + assert.equal(host.isIdle(), false); + + host.emit("turn_start"); + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); + host.recordWake(); + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + host.settle(); + await tick(); + + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 1); +}); + +test("a wake whose run never starts is retried instead of losing the answer", async () => { + const { host, requestId } = await withBackgroundForm(); + host.failNextWake(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); + assert.equal(host.isIdle(), true, "the run failed to start"); + + // The host reports the run settled: the branch still lacks the answer, so + // the in-flight send was never delivered and must be offered again. + host.settle(); + await tick(); + assert.equal(host.sent.length, 2); + assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); + assert.equal(host.sent[1]?.message.details.requestId, requestId); + + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); + assert.equal(host.sent.length, 2); +}); + +test("an adopted tool answer whose wake never starts is retried here, once", async () => { + const session = await unrecordedToolSession(); + const host = boot(session, { persistToolResults: false }); + host.failNextWake(); + await start(host); + assert.equal(host.sent.length, 1, "the rebuild adopts the answer as a wake"); + assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); + assert.equal(host.isIdle(), true, "the run failed to start"); + + // The branch still lacks the adopted answer, so it must be offered again + // in this process instead of waiting for the next reload or fork. + host.settle(); + await tick(); + assert.equal(host.sent.length, 2, "the failed adoption is retried"); + assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); + + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); + assert.equal(host.sent.length, 2); +}); + +test("a new run releases an answer whose wake never started, and delivers it once", async () => { + const { host, requestId } = await withBackgroundForm(); + host.failNextWake(); + host.type(...SUBMIT_TWO); + await tick(); + assert.equal(host.sent.length, 1); + + // Another run starts. The answer joins it at its first turn boundary. + host.setIdle(false); + host.emit("agent_start"); + const boundary = host.turnEnd(); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.entries[0].details.requestId, requestId); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 1); + assert.equal(host.sent.length, 1, "no second wake was needed"); +}); + +test("a working agent gets the answer at the next turn boundary, once, with no extra turn started", async () => { + const { host, requestId } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + await tick(); + assert.deepEqual(host.sent, [], "nothing is sent while the agent works"); + + const first = host.turnEnd(); + assert.equal(first.continue, true, "the answer must be seen even on a final turn"); + assert.equal(first.entries.length, 1); + assert.equal(first.entries[0].type, "custom_message"); + assert.equal(first.entries[0].customType, ASK_ANSWER_MESSAGE_TYPE); + assert.equal(first.entries[0].details.requestId, requestId); + assert.match(first.entries[0].content, /db "Which database\?": Postgres/); + + // Turn boundary, then settle: the same answer is not offered or sent again. + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); + host.settle(); + await tick(); + assert.deepEqual(host.sent, []); + assert.equal(host.answers().length, 1); +}); + +test("an answer given after the last turn joins at the settle boundary", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.turnEnd(); + host.type(...SUBMIT_TWO); + const boundary = host.beforeSettle(); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, true); + host.settle(); + await tick(); + assert.deepEqual(host.sent, []); + assert.equal(host.answers().length, 1); +}); + +test("boundary entries from other extensions are kept", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + const other = { type: "custom", customType: "other", data: 1 }; + const [result] = host.emit("turn_end", { entries: [other], message: {} }) as any[]; + assert.equal(result.entries.length, 2); + assert.equal(result.entries[0], other); +}); + +test("an answer left over after the user aborts is added without restarting the agent", async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + // The aborted turn's boundary adds the answer but asks for nothing more. + const aborted = boot(host.session); + await start(aborted); + assert.equal(aborted.sent.length, 1, "control: a fresh idle process would wake"); + + const { host: second } = await withBackgroundForm(); + second.setIdle(false); + second.type(...SUBMIT_TWO); + const boundary = second.turnEnd({ stopReason: "aborted" }); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, false); + + const { host: third } = await withBackgroundForm(); + third.setIdle(false); + third.type(...SUBMIT_TWO); + third.settle(true); + await tick(); + assert.equal(third.sent.length, 1); + assert.deepEqual(third.sent[0]?.options, { triggerTurn: false }); + assert.equal(third.answers().length, 1); +}); + +test("no duplicate delivery after reload, resume or a second session_start", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + host.recordWake(); + host.settle(); + assert.equal(host.sent.length, 1); + + await start(host, "reload"); + host.emit("session_tree"); + host.emit("session_compact"); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.panelText(), ""); + + // A later process on the same session sees the message on the branch. + const later = boot(host.session); + await start(later); + later.turnEnd(); + later.settle(); + await tick(); + assert.deepEqual(later.sent, []); + assert.equal(later.panelText(), ""); + assert.equal(later.answers().length, 1); +}); + +test("an outcome journalled but never recorded is delivered on the next start, once", async () => { + // The process dies after the answer was accepted but before the run wrote it. + const dying = boot(undefined, {}); + await start(dying, "startup"); + const receipt = await dying.askInBackground(); + dying.type(...SUBMIT_TWO); + await tick(); + assert.equal(dying.sent.length, 1); + assert.equal(dying.answers().length, 0); + + const host = boot(dying.session); + await start(host); + await start(host, "reload"); + assert.equal(host.panelText(), "", "an answered form is not shown again"); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, receipt.details.requestId); + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(host.sent.length, 1); +}); + +test("an answer whose tool result never reached the branch is delivered on attach", async () => { + // The process died after the outcome was journalled but before Pi wrote + // the tool result: the branch has the answer, the agent never saw it. + const dying = boot(undefined, { persistToolResults: false }); + const pending = dying.ask(); + await tick(); + dying.forms[0]?.press(...SUBMIT_TWO); + const response = await pending; + assert.equal(response.details.status, "submitted"); + assert.equal(dying.answers().length, 0); + assert.equal(dying.journal().at(-1)?.channel, "tool"); + + const host = boot(dying.session); + await start(host, "resume"); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, response.details.requestId); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: true }); + + host.recordWake(); + await start(host, "reload"); + assert.equal(host.sent.length, 1, "the answer message proves delivery"); + assert.equal(host.answers().length, 1); +}); + +test("a tool result on the branch proves the answer was delivered", async () => { + const dying = boot(undefined, { persistToolResults: false }); + const pending = dying.ask(); + await tick(); + dying.forms[0]?.press(...SUBMIT_TWO); + await pending; + dying.session.appendMessage({ + role: "toolResult", + toolCallId: "call-1", + toolName: "ask_user", + content: [{ type: "text", text: "answered" }], + isError: false, + timestamp: Date.now(), + }); + + const host = boot(dying.session); + await start(host, "resume"); + assert.deepEqual(host.sent, []); +}); + +test("a cancellation is recorded as context and never wakes or aborts the agent", async () => { + const { host, requestId } = await withBackgroundForm(); + // Dismiss, confirmed because the form has a draft. + host.type(KEY.enter, KEY.ctrlC, KEY.ctrlC); + await tick(); + + assert.equal(host.sent.length, 1); + assert.deepEqual(host.sent[0]?.options, { triggerTurn: false }); + assert.equal( + host.sent[0]?.message.content, + [ + `User cancelled your earlier ask_user form ${requestId} (Storage). Cancellation is not approval; keep risky actions blocked.`, + '- db "Which database?"', + '- cache "Which cache?"', + ].join("\n") + ); + assert.equal(host.isIdle(), true, "no turn was started"); + assert.equal(host.aborts, 0, "unrelated agent work is not aborted"); + assert.equal(host.journal().at(-1).result.status, "cancelled"); + assert.equal(host.panelText(), ""); + + host.settle(); + await start(host, "reload"); + const later = boot(host.session); + await start(later); + assert.equal(host.sent.length, 1); + assert.deepEqual(later.sent, []); + assert.equal(later.panelText(), ""); +}); + +test("a cancellation while the agent works joins the turn boundary without asking for a turn", async () => { + const { host } = await withBackgroundForm(ONE("a")); + await host.askInBackground(ONE("b")); + host.setIdle(false); + host.type(KEY.ctrlC); + await tick(); + assert.match(host.panelText(), /Pick b\?/, "only the cancelled form closed"); + assert.deepEqual(host.sent, []); + assert.equal(host.aborts, 0); + + const boundary = host.turnEnd({ stopReason: "stop" }); + assert.equal(boundary.entries.length, 1); + assert.equal(boundary.continue, false); + assert.match(boundary.entries[0].content, /cancelled/); +}); + +test("delivered answers render as a compact card", async () => { + const { host } = await withBackgroundForm(); + host.type(...SUBMIT_TWO); + await tick(); + const render = host.renderers.get(ASK_ANSWER_MESSAGE_TYPE); + const theme = { + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + const card = render?.(host.sent[0]?.message, { expanded: false }, theme); + const text = card.render(80).join("\n"); + assert.match(text, /ask_user answered · Storage/); + assert.match(text, /✓ DB: Postgres/); + assert.doesNotMatch(text, /requestId|\{/); + assert.equal(render?.({ details: undefined }, {}, theme), undefined); +}); diff --git a/pi-ask/tests/background-panel.test.ts b/pi-ask/tests/background-panel.test.ts new file mode 100644 index 00000000..3cf7f72e --- /dev/null +++ b/pi-ask/tests/background-panel.test.ts @@ -0,0 +1,191 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; +import { + boot, + start, + kinds, + ids, + ONE, + SUBMIT_ONE, + SUBMIT_TWO, + withBackgroundForm, +} from "./support/background.ts"; + +beforeEach(quietConfig); + +// --- The panel ------------------------------------------------------------- + +test("the panel sits above the editor, which keeps its text and its keyboard", async () => { + const host = boot(); + await start(host, "startup"); + host.type("d", "r", "a", "f", "t"); + await host.askInBackground(); + + assert.match(host.panelText(), /Which database\?/); + assert.equal(host.widgets.get("pi-ask:panel")?.placement, "aboveEditor"); + assert.ok(host.focusIs("editor"), "a message in progress keeps the keyboard"); + host.type("!", KEY.enter); + assert.equal(host.editor.text, `draft!${KEY.enter}`, "ordinary input still works"); + assert.deepEqual(kinds(host), ["form"], "typing did not touch the form"); + + // One key moves the keyboard into the panel and back. + host.type(KEY.focus); + assert.ok(host.focusIs("panel")); + host.type(KEY.enter); + assert.equal(host.journal().at(-1).kind, "draft"); + assert.equal(host.editor.text, `draft!${KEY.enter}`, "the draft message is intact"); + host.type(KEY.focus); + assert.ok(host.focusIs("editor")); + assert.match(host.panelText(), /answer here/); +}); + +test("a new form takes the keyboard when no message is being written", async () => { + const { host } = await withBackgroundForm(); + assert.ok(host.focusIs("panel")); + assert.match(host.panelText(), /hide/); + assert.match(host.panelText(), /cancel form/); +}); + +test("hiding cancels nothing, survives a reload, and only the user reopens", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(KEY.enter, KEY.escape); + assert.equal(host.panelText(), ""); + assert.ok(host.focusIs("editor")); + assert.deepEqual(kinds(host), ["form", "draft", "panel"]); + assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); + assert.match(host.indicator() ?? "", /\/ask-panel/); + + // A new request neither reopens the panel nor takes the keyboard. + const second = await host.askInBackground(ONE("x")); + assert.equal(second.details.pending, 2); + assert.equal(host.panelText(), ""); + assert.ok(host.focusIs("editor")); + assert.equal(host.notices.length, 1); + assert.match(host.indicator() ?? "", /2 unanswered questions in 2 forms/); + host.type("h", "i"); + assert.equal(host.editor.text, "hi"); + + // Still hidden for a later process on the same branch. + const later = boot(host.session); + await start(later); + assert.equal(later.panelText(), ""); + assert.ok(later.focusIs("editor")); + assert.match(later.indicator() ?? "", /2 unanswered questions in 2 forms/); + + await later.command("ask-panel"); + assert.ok(later.focusIs("panel")); + assert.match(later.panelText(), /Which cache\?/, "the draft came back"); + later.type(KEY.enter, KEY.enter); + await tick(); + assert.equal(later.sent[0]?.message.details.requestId, requestId); + assert.match(later.panelText(), /Pick x\?/, "the next form follows"); +}); + +test("the focus key reopens a hidden panel; with nothing waiting it is an ordinary key", async () => { + const host = boot(); + await start(host, "startup"); + host.type(KEY.focus); + assert.equal(host.editor.text, KEY.focus, "passed through to the editor"); + await host.command("ask-panel"); + assert.deepEqual(host.notices, ["No questions are waiting"]); + + host.editor.text = ""; + await host.askInBackground(); + host.type(KEY.later); + assert.equal(host.panelText(), "", "the later key hides the panel too"); + host.type(KEY.focus); + assert.ok(host.focusIs("panel")); + assert.deepEqual(kinds(host), ["form", "panel", "panel"]); + assert.equal(host.journal().at(-1).hidden, false); +}); + +test("the pending indicator counts unanswered questions and clears", async () => { + const { host } = await withBackgroundForm(); + assert.match(host.indicator() ?? "", /2 unanswered questions in 1 form/); + assert.equal(host.widgets.get("pi-ask:pending")?.placement, "belowEditor"); + host.type(KEY.enter); + assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); + host.type(KEY.enter); + assert.match(host.indicator() ?? "", /1 form ready to submit/); + host.type(KEY.enter); + await tick(); + assert.equal(host.indicator(), undefined); + assert.equal(host.widgets.size, 0); + assert.ok(host.focusIs("editor")); +}); + +test("forms are shown one at a time in request order, across defer and reopen", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(ONE("a")); + // B is asked second as a blocking form and deferred; C arrives after. + const blocking = host.ask(ONE("b")); + await tick(); + host.forms[0]?.press(KEY.down, KEY.later); + const deferred = await blocking; + assert.equal(deferred.details.status, "deferred"); + await host.askInBackground(ONE("c")); + const [a, b, c] = ids(host); + + assert.match(host.panelText(), /Pick a\?/); + assert.doesNotMatch(host.panelText(), /Pick [bc]\?/); + + // A later process rebuilds the same order from the branch. + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + const order: string[] = []; + for (const expected of ["a", "b", "c"]) { + assert.match(later.panelText(), new RegExp(`Pick ${expected}\\?`)); + later.type(...SUBMIT_ONE); + await tick(); + later.recordWake(); + order.push(later.answers().at(-1).details.requestId); + later.settle(); + } + assert.deepEqual(order, [a, b, c]); + assert.equal(later.panelText(), ""); +}); + +// --- Ownership ------------------------------------------------------------- + +test("a blocking call takes the keyboard from an open background form and gives it back", async () => { + const { host, requestId } = await withBackgroundForm(); + host.type(KEY.enter); + assert.ok(host.focusIs("panel")); + + const blocking = host.ask(ONE("urgent")); + await tick(); + assert.equal(host.panelText(), "", "only one form is on screen"); + assert.ok(host.focusIs("form")); + // Every key reaches the blocking form: no listener or panel swallows it. + host.type(KEY.focus); + host.type(...SUBMIT_ONE); + const response = await blocking; + assert.equal(response.details.status, "submitted"); + assert.deepEqual(response.details.answers.urgent.values, ["yes"]); + + // The background form is back as it was, with the keyboard. + assert.match(host.panelText(), /Which cache\?/); + assert.ok(host.focusIs("panel")); + host.type(KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.equal(host.sent[0]?.message.details.requestId, requestId); +}); + +test("a blocking form open in this process is never queued as interrupted", async () => { + const host = boot(); + const pending = host.ask(); + await tick(); + host.emit("session_tree"); + await start(host, "reload"); + assert.equal(host.forms.length, 1); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + + host.forms[0]?.press(...SUBMIT_TWO); + assert.equal((await pending).details.status, "submitted"); + assert.deepEqual(host.sent, []); +}); diff --git a/pi-ask/tests/background-recovery.test.ts b/pi-ask/tests/background-recovery.test.ts new file mode 100644 index 00000000..7493e008 --- /dev/null +++ b/pi-ask/tests/background-recovery.test.ts @@ -0,0 +1,283 @@ +import assert from "node:assert/strict"; +import test, { beforeEach, mock } from "node:test"; +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; +import { getAskConfigStore } from "../src/config/store.ts"; +import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; +import { + boot, + start, + kinds, + PARAMS, + SUBMIT_TWO, + interruptedSession, +} from "./support/background.ts"; + +beforeEach(quietConfig); + +// --- Recovery and branches ------------------------------------------------- + +test("an interrupted form comes back in the panel with its draft and is answered once", async () => { + const session = await interruptedSession(); + const host = boot(session); + const returned = host.emit("session_start", { reason: "resume" }); + assert.deepEqual(returned, [undefined], "the handler returns at once"); + await tick(); + + assert.equal(host.forms.length, 0, "recovery does not block the input"); + assert.match(host.panelText(), /Which cache\?/, "DB came back from the draft"); + assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); + assert.equal(host.notices.length, 1); + assert.equal(host.sent.length, 0); + + host.type(KEY.focus, KEY.enter, KEY.enter); + await tick(); + assert.equal(host.sent.length, 1); + assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); + assert.match(host.sent[0]?.message.content ?? "", /cache "Which cache\?": Redis/); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); +}); + +test("a form the conversation moved past is not brought back", async () => { + const session = await interruptedSession(); + session.appendMessage({ role: "user", content: "never mind", timestamp: Date.now() }); + const host = boot(session); + await start(host); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + assert.deepEqual(host.sent, []); +}); + +test("a form from another branch is not shown and writes nothing", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + const first = boot(session); + await start(first, "startup"); + await first.askInBackground(); + first.type(KEY.enter); + assert.equal(first.journal().length, 2); + + // Branch B forks from before the form was asked. + session.branch(rootId); + session.appendMessage({ role: "user", content: "other", timestamp: Date.now() }); + const host = boot(session); + await start(host); + host.emit("session_tree"); + await tick(); + assert.equal(host.panelText(), ""); + assert.equal(host.indicator(), undefined); + assert.deepEqual(host.sent, []); + assert.deepEqual(host.journal(), []); +}); + +test("a stale form cannot write into the branch the user moved to", async () => { + const session = SessionManager.inMemory(); + const rootId = session.appendMessage({ + role: "user", + content: "start", + timestamp: Date.now(), + }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + // Keep hold of the form as it is on screen, as a late callback would. + const stale = host.widgets.get("pi-ask:panel")?.component; + assert.ok(stale); + const handleInput = stale.handleInput?.bind(stale); + + session.branch(rootId); + host.emit("session_tree"); + assert.equal(host.panelText(), "", "the panel follows the branch at once"); + for (const key of SUBMIT_TWO) { + handleInput?.(key); + } + host.type(KEY.focus, ...SUBMIT_TWO); + await tick(); + + assert.deepEqual(host.sent, []); + assert.deepEqual(host.journal(), [], "nothing was written into this branch"); + assert.equal(host.turnEnd().entries.length, 0); + + // Back on the original branch the form is still waiting, unanswered. + const original = boot(session); + session.branch(session.getEntries().at(-1)?.id ?? rootId); + await start(original); + assert.deepEqual(original.sent, []); +}); + +test("the queue is TUI-only and a torn-down runtime writes nothing", async () => { + const session = await interruptedSession(); + const rpc = boot(session, { mode: "rpc" }); + await start(rpc); + assert.equal(rpc.widgets.size, 0); + assert.deepEqual(rpc.sent, []); + + const host = boot(session); + await start(host); + assert.match(host.panelText(), /Which cache\?/); + const panel = host.widgets.get("pi-ask:panel")?.component; + host.emit("session_shutdown", { reason: "quit" }); + assert.equal(host.widgets.size, 0); + panel?.handleInput?.(KEY.enter); + panel?.handleInput?.(KEY.enter); + host.type(KEY.focus); + await tick(); + assert.deepEqual(host.sent, []); + assert.deepEqual(kinds(host), ["form", "draft"]); + assert.equal(host.turnEnd().entries.length, 0); +}); + +const TEXT_FORM = { + title: "Notes", + questions: [{ id: "dir", label: "DIR", prompt: "Which directory?", type: "text" }], +}; + +test("text typed in an editor survives a restart, written once typing pauses", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + assert.ok(host.focusIs("panel"), "a new form takes the idle keyboard"); + + mock.timers.enable({ apis: ["setTimeout"] }); + try { + host.type(..."src/ui"); + assert.deepEqual(kinds(host), ["form"], "keystrokes are not written one by one"); + mock.timers.tick(5000); + } finally { + mock.timers.reset(); + } + assert.deepEqual(kinds(host), ["form", "draft"], "one draft for the burst"); + + // A key that ends the typing writes at once, with the text folded in. + host.type("/"); + host.type(KEY.escape); + assert.deepEqual(kinds(host), ["form", "draft", "draft"]); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /src\/ui\//, "the unfinished answer came back"); +}); + +test("an editor still open when Pi quits is journalled on dispose", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + host.type(..."draft text"); + assert.deepEqual(kinds(host), ["form"]); + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), ["form", "draft"]); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /draft text/); +}); + +test("a tree move rebuilds a kept form from the branch, dropping rolled-back answers", async () => { + const session = SessionManager.inMemory(); + session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + const formEntry = session.getBranch().at(-1)?.id; + assert.ok(formEntry); + host.type(KEY.enter); + assert.match(host.panelText(), /Which cache\?/, "DB answered, cache is next"); + assert.deepEqual(kinds(host), ["form", "draft"]); + + // Back to the moment the form was asked: the answer is not on this branch. + session.branch(formEntry); + host.emit("session_tree"); + await tick(); + assert.deepEqual(kinds(host), ["form"]); + assert.match(host.panelText(), /Which database\?/, "the rolled-back answer is gone"); + assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); + + host.type(KEY.focus, ...SUBMIT_TWO); + await tick(); + assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); + assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); +}); + +test("a tree move to the same branch keeps the form, with its unsent text", async () => { + const host = boot(); + await start(host, "startup"); + await host.askInBackground(TEXT_FORM); + host.type(..."keep"); + host.emit("session_tree"); + await tick(); + assert.match(host.panelText(), /keep/); + host.type(KEY.focus, ..."me"); + assert.match(host.panelText(), /keepme/); +}); + +test("a form rebuilt after a tree move does not notify the user again", async () => { + getAskConfigStore().setConfig({ + ...DEFAULT_ASK_CONFIG, + notifications: { channels: ["bell"], enabled: true }, + }); + const bells = () => writes.mock.calls.filter((call) => call.arguments[0] === "\x07").length; + const writes = mock.method(process.stdout, "write", () => true); + try { + const session = SessionManager.inMemory(); + session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); + const host = boot(session); + await start(host, "startup"); + await host.askInBackground(); + await tick(); + assert.equal(bells(), 1, "the user is told once, when the form first appears"); + const formEntry = session.getBranch().at(-1)?.id; + assert.ok(formEntry); + host.type(KEY.enter); + + session.branch(formEntry); + host.emit("session_tree"); + await tick(); + assert.match(host.panelText(), /Which database\?/, "the form was rebuilt"); + assert.equal(bells(), 1, "a rebuilt form is not announced again"); + } finally { + writes.mock.restore(); + } +}); + +test("a blocking form's last keystrokes are journalled on shutdown", async () => { + const host = boot(); + await start(host, "startup"); + const pending = host.ask(TEXT_FORM); + pending.catch(() => {}); + await tick(); + mock.timers.enable({ apis: ["setTimeout"] }); + try { + host.forms[0]?.press(..."src/ui"); + assert.deepEqual(kinds(host), ["form"], "typing waits for the pause"); + // Pi quits before the typing timer fires. + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), ["form", "draft"]); + mock.timers.tick(5000); + } finally { + mock.timers.reset(); + } + assert.deepEqual(kinds(host), ["form", "draft"], "nothing is written twice"); + + const later = boot(host.session); + await start(later); + await later.command("ask-panel"); + assert.match(later.panelText(), /src\/ui/, "the unfinished answer came back"); +}); + +test("a finished blocking form is not flushed again on shutdown", async () => { + const host = boot(); + await start(host, "startup"); + const pending = host.ask(PARAMS); + await tick(); + host.forms[0]?.press(...SUBMIT_TWO); + await pending; + const before = kinds(host); + host.emit("session_shutdown", { reason: "quit" }); + assert.deepEqual(kinds(host), before); +}); diff --git a/pi-ask/tests/background.test.ts b/pi-ask/tests/background.test.ts index 23567bfd..7d9ee0b8 100644 --- a/pi-ask/tests/background.test.ts +++ b/pi-ask/tests/background.test.ts @@ -1,109 +1,16 @@ import assert from "node:assert/strict"; -import test, { beforeEach, mock } from "node:test"; -import { SessionManager } from "@earendil-works/pi-coding-agent"; +import test, { beforeEach } from "node:test"; import { registerAskTool } from "../src/ask-tool.ts"; -import { registerAskBackground } from "../src/background.ts"; -import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; -import { getAskConfigStore } from "../src/config/store.ts"; -import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; -import { createAskRuntime } from "../src/runtime.ts"; import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; - -const question = (id: string, prompt: string, first: string, second: string) => ({ - id, - label: id.toUpperCase(), - prompt, - options: [ - { value: first.toLowerCase(), label: first }, - { value: second.toLowerCase(), label: second }, - ], -}); - -const PARAMS = { - title: "Storage", - questions: [ - question("db", "Which database?", "Postgres", "SQLite"), - question("cache", "Which cache?", "Redis", "None"), - ], -}; -const ONE = (id: string, title = id) => ({ - title, - questions: [question(id, `Pick ${id}?`, "Yes", "No")], -}); -/** Answer every question with its first option and submit. */ -const SUBMIT_TWO = [KEY.enter, KEY.enter, KEY.enter]; -const SUBMIT_ONE = [KEY.enter, KEY.enter]; - -/** One Pi process: the extension wired as `src/index.ts` wires it. */ -function boot( - session?: SessionManager, - options: { - background?: boolean; - mode?: string; - persistToolResults?: boolean; - } = {} -) { - const host = fakePi(session, options); - const runtime = createAskRuntime(host.pi); - registerAskBackground(host.pi, runtime); - registerAskTool(host.pi, { - runtime, - features: { background: options.background ?? true, expiry: false }, - }); - let calls = 0; - const ask = (params: object = PARAMS) => - host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); - const askInBackground = (params: object = PARAMS) => - ask({ ...params, background: true }); - return { ...host, host, ask, askInBackground }; -} - -type Host = ReturnType; - -async function start(host: Host, reason = "resume") { - host.emit("session_start", { reason }); - await tick(); -} - -const kinds = (host: Host) => host.journal().map((entry) => entry.kind); -const ids = (host: Host) => - host - .journal() - .filter((entry) => entry.kind === "form") - .map((entry) => entry.requestId); - -/** A session whose foreground form was open, DB answered, when Pi died. */ -async function interruptedSession() { - const first = boot(); - first.ask().catch(() => {}); - await tick(); - first.forms[0]?.press(KEY.enter); - assert.deepEqual(kinds(first), ["form", "draft"]); - return first.session; -} - -/** A started process with one background form in the focused panel. */ -async function withBackgroundForm(params: object = PARAMS) { - const host = boot(); - await start(host, "startup"); - const receipt = await host.askInBackground(params); - return { host, receipt, requestId: receipt.details.requestId as string }; -} - -/** - * A session whose blocking form was answered, but where Pi died before it - * wrote the tool result: the answer exists only in the journal. - */ -async function unrecordedToolSession() { - const first = boot(undefined, { persistToolResults: false }); - const pending = first.ask(); - await tick(); - first.forms[0]?.press(...SUBMIT_TWO); - await pending; - assert.equal(first.journal().at(-1)?.channel, "tool"); - assert.equal(first.answers().length, 0); - return first.session; -} +import { + boot, + start, + kinds, + PARAMS, + ONE, + SUBMIT_TWO, + withBackgroundForm, +} from "./support/background.ts"; beforeEach(quietConfig); @@ -207,140 +114,6 @@ test("hosts without the TUI block on a background call or report unavailable", a assert.deepEqual(kinds(json), ["form", "outcome"]); }); -// --- The panel ------------------------------------------------------------- - -test("the panel sits above the editor, which keeps its text and its keyboard", async () => { - const host = boot(); - await start(host, "startup"); - host.type("d", "r", "a", "f", "t"); - await host.askInBackground(); - - assert.match(host.panelText(), /Which database\?/); - assert.equal(host.widgets.get("pi-ask:panel")?.placement, "aboveEditor"); - assert.ok(host.focusIs("editor"), "a message in progress keeps the keyboard"); - host.type("!", KEY.enter); - assert.equal(host.editor.text, `draft!${KEY.enter}`, "ordinary input still works"); - assert.deepEqual(kinds(host), ["form"], "typing did not touch the form"); - - // One key moves the keyboard into the panel and back. - host.type(KEY.focus); - assert.ok(host.focusIs("panel")); - host.type(KEY.enter); - assert.equal(host.journal().at(-1).kind, "draft"); - assert.equal(host.editor.text, `draft!${KEY.enter}`, "the draft message is intact"); - host.type(KEY.focus); - assert.ok(host.focusIs("editor")); - assert.match(host.panelText(), /answer here/); -}); - -test("a new form takes the keyboard when no message is being written", async () => { - const { host } = await withBackgroundForm(); - assert.ok(host.focusIs("panel")); - assert.match(host.panelText(), /hide/); - assert.match(host.panelText(), /cancel form/); -}); - -test("hiding cancels nothing, survives a reload, and only the user reopens", async () => { - const { host, requestId } = await withBackgroundForm(); - host.type(KEY.enter, KEY.escape); - assert.equal(host.panelText(), ""); - assert.ok(host.focusIs("editor")); - assert.deepEqual(kinds(host), ["form", "draft", "panel"]); - assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); - assert.match(host.indicator() ?? "", /\/ask-panel/); - - // A new request neither reopens the panel nor takes the keyboard. - const second = await host.askInBackground(ONE("x")); - assert.equal(second.details.pending, 2); - assert.equal(host.panelText(), ""); - assert.ok(host.focusIs("editor")); - assert.equal(host.notices.length, 1); - assert.match(host.indicator() ?? "", /2 unanswered questions in 2 forms/); - host.type("h", "i"); - assert.equal(host.editor.text, "hi"); - - // Still hidden for a later process on the same branch. - const later = boot(host.session); - await start(later); - assert.equal(later.panelText(), ""); - assert.ok(later.focusIs("editor")); - assert.match(later.indicator() ?? "", /2 unanswered questions in 2 forms/); - - await later.command("ask-panel"); - assert.ok(later.focusIs("panel")); - assert.match(later.panelText(), /Which cache\?/, "the draft came back"); - later.type(KEY.enter, KEY.enter); - await tick(); - assert.equal(later.sent[0]?.message.details.requestId, requestId); - assert.match(later.panelText(), /Pick x\?/, "the next form follows"); -}); - -test("the focus key reopens a hidden panel; with nothing waiting it is an ordinary key", async () => { - const host = boot(); - await start(host, "startup"); - host.type(KEY.focus); - assert.equal(host.editor.text, KEY.focus, "passed through to the editor"); - await host.command("ask-panel"); - assert.deepEqual(host.notices, ["No questions are waiting"]); - - host.editor.text = ""; - await host.askInBackground(); - host.type(KEY.later); - assert.equal(host.panelText(), "", "the later key hides the panel too"); - host.type(KEY.focus); - assert.ok(host.focusIs("panel")); - assert.deepEqual(kinds(host), ["form", "panel", "panel"]); - assert.equal(host.journal().at(-1).hidden, false); -}); - -test("the pending indicator counts unanswered questions and clears", async () => { - const { host } = await withBackgroundForm(); - assert.match(host.indicator() ?? "", /2 unanswered questions in 1 form/); - assert.equal(host.widgets.get("pi-ask:pending")?.placement, "belowEditor"); - host.type(KEY.enter); - assert.match(host.indicator() ?? "", /1 unanswered question in 1 form/); - host.type(KEY.enter); - assert.match(host.indicator() ?? "", /1 form ready to submit/); - host.type(KEY.enter); - await tick(); - assert.equal(host.indicator(), undefined); - assert.equal(host.widgets.size, 0); - assert.ok(host.focusIs("editor")); -}); - -test("forms are shown one at a time in request order, across defer and reopen", async () => { - const host = boot(); - await start(host, "startup"); - await host.askInBackground(ONE("a")); - // B is asked second as a blocking form and deferred; C arrives after. - const blocking = host.ask(ONE("b")); - await tick(); - host.forms[0]?.press(KEY.down, KEY.later); - const deferred = await blocking; - assert.equal(deferred.details.status, "deferred"); - await host.askInBackground(ONE("c")); - const [a, b, c] = ids(host); - - assert.match(host.panelText(), /Pick a\?/); - assert.doesNotMatch(host.panelText(), /Pick [bc]\?/); - - // A later process rebuilds the same order from the branch. - const later = boot(host.session); - await start(later); - await later.command("ask-panel"); - const order: string[] = []; - for (const expected of ["a", "b", "c"]) { - assert.match(later.panelText(), new RegExp(`Pick ${expected}\\?`)); - later.type(...SUBMIT_ONE); - await tick(); - later.recordWake(); - order.push(later.answers().at(-1).details.requestId); - later.settle(); - } - assert.deepEqual(order, [a, b, c]); - assert.equal(later.panelText(), ""); -}); - // --- Defer ----------------------------------------------------------------- test("answer later returns a deferred receipt and keeps the draft for the panel", async () => { @@ -383,651 +156,3 @@ test("answer later is not offered where there is no queue to move to", async () host.forms[0]?.press(KEY.later, ...SUBMIT_TWO); assert.equal((await pending).details.status, "submitted"); }); - -// --- Ownership ------------------------------------------------------------- - -test("a blocking call takes the keyboard from an open background form and gives it back", async () => { - const { host, requestId } = await withBackgroundForm(); - host.type(KEY.enter); - assert.ok(host.focusIs("panel")); - - const blocking = host.ask(ONE("urgent")); - await tick(); - assert.equal(host.panelText(), "", "only one form is on screen"); - assert.ok(host.focusIs("form")); - // Every key reaches the blocking form: no listener or panel swallows it. - host.type(KEY.focus); - host.type(...SUBMIT_ONE); - const response = await blocking; - assert.equal(response.details.status, "submitted"); - assert.deepEqual(response.details.answers.urgent.values, ["yes"]); - - // The background form is back as it was, with the keyboard. - assert.match(host.panelText(), /Which cache\?/); - assert.ok(host.focusIs("panel")); - host.type(KEY.enter, KEY.enter); - await tick(); - assert.equal(host.sent.length, 1); - assert.equal(host.sent[0]?.message.details.requestId, requestId); -}); - -test("a blocking form open in this process is never queued as interrupted", async () => { - const host = boot(); - const pending = host.ask(); - await tick(); - host.emit("session_tree"); - await start(host, "reload"); - assert.equal(host.forms.length, 1); - assert.equal(host.panelText(), ""); - assert.equal(host.indicator(), undefined); - - host.forms[0]?.press(...SUBMIT_TWO); - assert.equal((await pending).details.status, "submitted"); - assert.deepEqual(host.sent, []); -}); - -// --- Delivery -------------------------------------------------------------- - -test("an idle agent is woken by the answer, which names the form and each question", async () => { - const { host, requestId } = await withBackgroundForm(); - host.type(...SUBMIT_TWO); - await tick(); - - assert.equal(host.sent.length, 1); - const [{ message, options }] = host.sent; - assert.equal(message.customType, ASK_ANSWER_MESSAGE_TYPE); - assert.deepEqual(options, { triggerTurn: true }); - assert.equal( - message.content, - [ - `User answered your earlier ask_user form ${requestId} (Storage):`, - '- db "Which database?": Postgres [postgres]', - '- cache "Which cache?": Redis [redis]', - ].join("\n") - ); - assert.equal(message.details.result.status, "submitted"); - assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); - assert.equal(host.journal().at(-1).channel, "message"); -}); - -test("no duplicate when the woken run reaches its turn boundary before the message is recorded", async () => { - const { host } = await withBackgroundForm(); - host.type(...SUBMIT_TWO); - await tick(); - assert.equal(host.sent.length, 1); - assert.equal(host.answers().length, 0, "the run has not recorded it yet"); - assert.equal(host.isIdle(), false); - - host.emit("turn_start"); - assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); - assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); - host.recordWake(); - assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); - host.settle(); - await tick(); - - assert.equal(host.sent.length, 1); - assert.equal(host.answers().length, 1); -}); - -test("a wake whose run never starts is retried instead of losing the answer", async () => { - const { host, requestId } = await withBackgroundForm(); - host.failNextWake(); - host.type(...SUBMIT_TWO); - await tick(); - assert.equal(host.sent.length, 1); - assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); - assert.equal(host.isIdle(), true, "the run failed to start"); - - // The host reports the run settled: the branch still lacks the answer, so - // the in-flight send was never delivered and must be offered again. - host.settle(); - await tick(); - assert.equal(host.sent.length, 2); - assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); - assert.equal(host.sent[1]?.message.details.requestId, requestId); - - host.recordWake(); - host.settle(); - await start(host, "reload"); - assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); - assert.equal(host.sent.length, 2); -}); - -test("an adopted tool answer whose wake never starts is retried here, once", async () => { - const session = await unrecordedToolSession(); - const host = boot(session, { persistToolResults: false }); - host.failNextWake(); - await start(host); - assert.equal(host.sent.length, 1, "the rebuild adopts the answer as a wake"); - assert.equal(host.answers().length, 0, "the failed wake never reached the branch"); - assert.equal(host.isIdle(), true, "the run failed to start"); - - // The branch still lacks the adopted answer, so it must be offered again - // in this process instead of waiting for the next reload or fork. - host.settle(); - await tick(); - assert.equal(host.sent.length, 2, "the failed adoption is retried"); - assert.deepEqual(host.sent[1]?.options, { triggerTurn: true }); - - host.recordWake(); - host.settle(); - await start(host, "reload"); - assert.equal(host.answers().length, 1, "the branch proves exactly one delivery"); - assert.equal(host.sent.length, 2); -}); - -test("a new run releases an answer whose wake never started, and delivers it once", async () => { - const { host, requestId } = await withBackgroundForm(); - host.failNextWake(); - host.type(...SUBMIT_TWO); - await tick(); - assert.equal(host.sent.length, 1); - - // Another run starts. The answer joins it at its first turn boundary. - host.setIdle(false); - host.emit("agent_start"); - const boundary = host.turnEnd(); - assert.equal(boundary.entries.length, 1); - assert.equal(boundary.entries[0].details.requestId, requestId); - host.settle(); - await start(host, "reload"); - assert.equal(host.answers().length, 1); - assert.equal(host.sent.length, 1, "no second wake was needed"); -}); - -test("a working agent gets the answer at the next turn boundary, once, with no extra turn started", async () => { - const { host, requestId } = await withBackgroundForm(); - host.setIdle(false); - host.type(...SUBMIT_TWO); - await tick(); - assert.deepEqual(host.sent, [], "nothing is sent while the agent works"); - - const first = host.turnEnd(); - assert.equal(first.continue, true, "the answer must be seen even on a final turn"); - assert.equal(first.entries.length, 1); - assert.equal(first.entries[0].type, "custom_message"); - assert.equal(first.entries[0].customType, ASK_ANSWER_MESSAGE_TYPE); - assert.equal(first.entries[0].details.requestId, requestId); - assert.match(first.entries[0].content, /db "Which database\?": Postgres/); - - // Turn boundary, then settle: the same answer is not offered or sent again. - assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); - assert.deepEqual(host.beforeSettle(), { entries: [], continue: false }); - host.settle(); - await tick(); - assert.deepEqual(host.sent, []); - assert.equal(host.answers().length, 1); -}); - -test("an answer given after the last turn joins at the settle boundary", async () => { - const { host } = await withBackgroundForm(); - host.setIdle(false); - host.turnEnd(); - host.type(...SUBMIT_TWO); - const boundary = host.beforeSettle(); - assert.equal(boundary.entries.length, 1); - assert.equal(boundary.continue, true); - host.settle(); - await tick(); - assert.deepEqual(host.sent, []); - assert.equal(host.answers().length, 1); -}); - -test("boundary entries from other extensions are kept", async () => { - const { host } = await withBackgroundForm(); - host.setIdle(false); - host.type(...SUBMIT_TWO); - const other = { type: "custom", customType: "other", data: 1 }; - const [result] = host.emit("turn_end", { entries: [other], message: {} }) as any[]; - assert.equal(result.entries.length, 2); - assert.equal(result.entries[0], other); -}); - -test("an answer left over after the user aborts is added without restarting the agent", async () => { - const { host } = await withBackgroundForm(); - host.setIdle(false); - host.type(...SUBMIT_TWO); - // The aborted turn's boundary adds the answer but asks for nothing more. - const aborted = boot(host.session); - await start(aborted); - assert.equal(aborted.sent.length, 1, "control: a fresh idle process would wake"); - - const { host: second } = await withBackgroundForm(); - second.setIdle(false); - second.type(...SUBMIT_TWO); - const boundary = second.turnEnd({ stopReason: "aborted" }); - assert.equal(boundary.entries.length, 1); - assert.equal(boundary.continue, false); - - const { host: third } = await withBackgroundForm(); - third.setIdle(false); - third.type(...SUBMIT_TWO); - third.settle(true); - await tick(); - assert.equal(third.sent.length, 1); - assert.deepEqual(third.sent[0]?.options, { triggerTurn: false }); - assert.equal(third.answers().length, 1); -}); - -test("no duplicate delivery after reload, resume or a second session_start", async () => { - const { host } = await withBackgroundForm(); - host.type(...SUBMIT_TWO); - await tick(); - host.recordWake(); - host.settle(); - assert.equal(host.sent.length, 1); - - await start(host, "reload"); - host.emit("session_tree"); - host.emit("session_compact"); - await tick(); - assert.equal(host.sent.length, 1); - assert.equal(host.panelText(), ""); - - // A later process on the same session sees the message on the branch. - const later = boot(host.session); - await start(later); - later.turnEnd(); - later.settle(); - await tick(); - assert.deepEqual(later.sent, []); - assert.equal(later.panelText(), ""); - assert.equal(later.answers().length, 1); -}); - -test("an outcome journalled but never recorded is delivered on the next start, once", async () => { - // The process dies after the answer was accepted but before the run wrote it. - const dying = boot(undefined, {}); - await start(dying, "startup"); - const receipt = await dying.askInBackground(); - dying.type(...SUBMIT_TWO); - await tick(); - assert.equal(dying.sent.length, 1); - assert.equal(dying.answers().length, 0); - - const host = boot(dying.session); - await start(host); - await start(host, "reload"); - assert.equal(host.panelText(), "", "an answered form is not shown again"); - assert.equal(host.sent.length, 1); - assert.equal(host.sent[0]?.message.details.requestId, receipt.details.requestId); - host.recordWake(); - host.settle(); - await start(host, "reload"); - assert.equal(host.sent.length, 1); -}); - -test("an answer whose tool result never reached the branch is delivered on attach", async () => { - // The process died after the outcome was journalled but before Pi wrote - // the tool result: the branch has the answer, the agent never saw it. - const dying = boot(undefined, { persistToolResults: false }); - const pending = dying.ask(); - await tick(); - dying.forms[0]?.press(...SUBMIT_TWO); - const response = await pending; - assert.equal(response.details.status, "submitted"); - assert.equal(dying.answers().length, 0); - assert.equal(dying.journal().at(-1)?.channel, "tool"); - - const host = boot(dying.session); - await start(host, "resume"); - assert.equal(host.sent.length, 1); - assert.equal(host.sent[0]?.message.details.requestId, response.details.requestId); - assert.deepEqual(host.sent[0]?.options, { triggerTurn: true }); - - host.recordWake(); - await start(host, "reload"); - assert.equal(host.sent.length, 1, "the answer message proves delivery"); - assert.equal(host.answers().length, 1); -}); - -test("a tool result on the branch proves the answer was delivered", async () => { - const dying = boot(undefined, { persistToolResults: false }); - const pending = dying.ask(); - await tick(); - dying.forms[0]?.press(...SUBMIT_TWO); - await pending; - dying.session.appendMessage({ - role: "toolResult", - toolCallId: "call-1", - toolName: "ask_user", - content: [{ type: "text", text: "answered" }], - isError: false, - timestamp: Date.now(), - }); - - const host = boot(dying.session); - await start(host, "resume"); - assert.deepEqual(host.sent, []); -}); - -test("a cancellation is recorded as context and never wakes or aborts the agent", async () => { - const { host, requestId } = await withBackgroundForm(); - // Dismiss, confirmed because the form has a draft. - host.type(KEY.enter, KEY.ctrlC, KEY.ctrlC); - await tick(); - - assert.equal(host.sent.length, 1); - assert.deepEqual(host.sent[0]?.options, { triggerTurn: false }); - assert.equal( - host.sent[0]?.message.content, - [ - `User cancelled your earlier ask_user form ${requestId} (Storage). Cancellation is not approval; keep risky actions blocked.`, - '- db "Which database?"', - '- cache "Which cache?"', - ].join("\n") - ); - assert.equal(host.isIdle(), true, "no turn was started"); - assert.equal(host.aborts, 0, "unrelated agent work is not aborted"); - assert.equal(host.journal().at(-1).result.status, "cancelled"); - assert.equal(host.panelText(), ""); - - host.settle(); - await start(host, "reload"); - const later = boot(host.session); - await start(later); - assert.equal(host.sent.length, 1); - assert.deepEqual(later.sent, []); - assert.equal(later.panelText(), ""); -}); - -test("a cancellation while the agent works joins the turn boundary without asking for a turn", async () => { - const { host } = await withBackgroundForm(ONE("a")); - await host.askInBackground(ONE("b")); - host.setIdle(false); - host.type(KEY.ctrlC); - await tick(); - assert.match(host.panelText(), /Pick b\?/, "only the cancelled form closed"); - assert.deepEqual(host.sent, []); - assert.equal(host.aborts, 0); - - const boundary = host.turnEnd({ stopReason: "stop" }); - assert.equal(boundary.entries.length, 1); - assert.equal(boundary.continue, false); - assert.match(boundary.entries[0].content, /cancelled/); -}); - -test("delivered answers render as a compact card", async () => { - const { host } = await withBackgroundForm(); - host.type(...SUBMIT_TWO); - await tick(); - const render = host.renderers.get(ASK_ANSWER_MESSAGE_TYPE); - const theme = { - fg: (_color: string, text: string) => text, - bold: (text: string) => text, - }; - const card = render?.(host.sent[0]?.message, { expanded: false }, theme); - const text = card.render(80).join("\n"); - assert.match(text, /ask_user answered · Storage/); - assert.match(text, /✓ DB: Postgres/); - assert.doesNotMatch(text, /requestId|\{/); - assert.equal(render?.({ details: undefined }, {}, theme), undefined); -}); - -// --- Recovery and branches ------------------------------------------------- - -test("an interrupted form comes back in the panel with its draft and is answered once", async () => { - const session = await interruptedSession(); - const host = boot(session); - const returned = host.emit("session_start", { reason: "resume" }); - assert.deepEqual(returned, [undefined], "the handler returns at once"); - await tick(); - - assert.equal(host.forms.length, 0, "recovery does not block the input"); - assert.match(host.panelText(), /Which cache\?/, "DB came back from the draft"); - assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); - assert.equal(host.notices.length, 1); - assert.equal(host.sent.length, 0); - - host.type(KEY.focus, KEY.enter, KEY.enter); - await tick(); - assert.equal(host.sent.length, 1); - assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); - assert.match(host.sent[0]?.message.content ?? "", /cache "Which cache\?": Redis/); - assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); -}); - -test("a form the conversation moved past is not brought back", async () => { - const session = await interruptedSession(); - session.appendMessage({ role: "user", content: "never mind", timestamp: Date.now() }); - const host = boot(session); - await start(host); - assert.equal(host.panelText(), ""); - assert.equal(host.indicator(), undefined); - assert.deepEqual(host.sent, []); -}); - -test("a form from another branch is not shown and writes nothing", async () => { - const session = SessionManager.inMemory(); - const rootId = session.appendMessage({ - role: "user", - content: "start", - timestamp: Date.now(), - }); - const first = boot(session); - await start(first, "startup"); - await first.askInBackground(); - first.type(KEY.enter); - assert.equal(first.journal().length, 2); - - // Branch B forks from before the form was asked. - session.branch(rootId); - session.appendMessage({ role: "user", content: "other", timestamp: Date.now() }); - const host = boot(session); - await start(host); - host.emit("session_tree"); - await tick(); - assert.equal(host.panelText(), ""); - assert.equal(host.indicator(), undefined); - assert.deepEqual(host.sent, []); - assert.deepEqual(host.journal(), []); -}); - -test("a stale form cannot write into the branch the user moved to", async () => { - const session = SessionManager.inMemory(); - const rootId = session.appendMessage({ - role: "user", - content: "start", - timestamp: Date.now(), - }); - const host = boot(session); - await start(host, "startup"); - await host.askInBackground(); - // Keep hold of the form as it is on screen, as a late callback would. - const stale = host.widgets.get("pi-ask:panel")?.component; - assert.ok(stale); - const handleInput = stale.handleInput?.bind(stale); - - session.branch(rootId); - host.emit("session_tree"); - assert.equal(host.panelText(), "", "the panel follows the branch at once"); - for (const key of SUBMIT_TWO) { - handleInput?.(key); - } - host.type(KEY.focus, ...SUBMIT_TWO); - await tick(); - - assert.deepEqual(host.sent, []); - assert.deepEqual(host.journal(), [], "nothing was written into this branch"); - assert.equal(host.turnEnd().entries.length, 0); - - // Back on the original branch the form is still waiting, unanswered. - const original = boot(session); - session.branch(session.getEntries().at(-1)?.id ?? rootId); - await start(original); - assert.deepEqual(original.sent, []); -}); - -test("the queue is TUI-only and a torn-down runtime writes nothing", async () => { - const session = await interruptedSession(); - const rpc = boot(session, { mode: "rpc" }); - await start(rpc); - assert.equal(rpc.widgets.size, 0); - assert.deepEqual(rpc.sent, []); - - const host = boot(session); - await start(host); - assert.match(host.panelText(), /Which cache\?/); - const panel = host.widgets.get("pi-ask:panel")?.component; - host.emit("session_shutdown", { reason: "quit" }); - assert.equal(host.widgets.size, 0); - panel?.handleInput?.(KEY.enter); - panel?.handleInput?.(KEY.enter); - host.type(KEY.focus); - await tick(); - assert.deepEqual(host.sent, []); - assert.deepEqual(kinds(host), ["form", "draft"]); - assert.equal(host.turnEnd().entries.length, 0); -}); - -const TEXT_FORM = { - title: "Notes", - questions: [{ id: "dir", label: "DIR", prompt: "Which directory?", type: "text" }], -}; - -test("text typed in an editor survives a restart, written once typing pauses", async () => { - const host = boot(); - await start(host, "startup"); - await host.askInBackground(TEXT_FORM); - assert.ok(host.focusIs("panel"), "a new form takes the idle keyboard"); - - mock.timers.enable({ apis: ["setTimeout"] }); - try { - host.type(..."src/ui"); - assert.deepEqual(kinds(host), ["form"], "keystrokes are not written one by one"); - mock.timers.tick(5000); - } finally { - mock.timers.reset(); - } - assert.deepEqual(kinds(host), ["form", "draft"], "one draft for the burst"); - - // A key that ends the typing writes at once, with the text folded in. - host.type("/"); - host.type(KEY.escape); - assert.deepEqual(kinds(host), ["form", "draft", "draft"]); - - const later = boot(host.session); - await start(later); - await later.command("ask-panel"); - assert.match(later.panelText(), /src\/ui\//, "the unfinished answer came back"); -}); - -test("an editor still open when Pi quits is journalled on dispose", async () => { - const host = boot(); - await start(host, "startup"); - await host.askInBackground(TEXT_FORM); - host.type(..."draft text"); - assert.deepEqual(kinds(host), ["form"]); - host.emit("session_shutdown", { reason: "quit" }); - assert.deepEqual(kinds(host), ["form", "draft"]); - - const later = boot(host.session); - await start(later); - await later.command("ask-panel"); - assert.match(later.panelText(), /draft text/); -}); - -test("a tree move rebuilds a kept form from the branch, dropping rolled-back answers", async () => { - const session = SessionManager.inMemory(); - session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); - const host = boot(session); - await start(host, "startup"); - await host.askInBackground(); - const formEntry = session.getBranch().at(-1)?.id; - assert.ok(formEntry); - host.type(KEY.enter); - assert.match(host.panelText(), /Which cache\?/, "DB answered, cache is next"); - assert.deepEqual(kinds(host), ["form", "draft"]); - - // Back to the moment the form was asked: the answer is not on this branch. - session.branch(formEntry); - host.emit("session_tree"); - await tick(); - assert.deepEqual(kinds(host), ["form"]); - assert.match(host.panelText(), /Which database\?/, "the rolled-back answer is gone"); - assert.ok(host.focusIs("editor"), "a rebuild never takes the keyboard"); - - host.type(KEY.focus, ...SUBMIT_TWO); - await tick(); - assert.match(host.sent[0]?.message.content ?? "", /db "Which database\?": Postgres/); - assert.deepEqual(kinds(host), ["form", "draft", "draft", "outcome"]); -}); - -test("a tree move to the same branch keeps the form, with its unsent text", async () => { - const host = boot(); - await start(host, "startup"); - await host.askInBackground(TEXT_FORM); - host.type(..."keep"); - host.emit("session_tree"); - await tick(); - assert.match(host.panelText(), /keep/); - host.type(KEY.focus, ..."me"); - assert.match(host.panelText(), /keepme/); -}); - -test("a form rebuilt after a tree move does not notify the user again", async () => { - getAskConfigStore().setConfig({ - ...DEFAULT_ASK_CONFIG, - notifications: { channels: ["bell"], enabled: true }, - }); - const bells = () => writes.mock.calls.filter((call) => call.arguments[0] === "\x07").length; - const writes = mock.method(process.stdout, "write", () => true); - try { - const session = SessionManager.inMemory(); - session.appendMessage({ role: "user", content: "start", timestamp: Date.now() }); - const host = boot(session); - await start(host, "startup"); - await host.askInBackground(); - await tick(); - assert.equal(bells(), 1, "the user is told once, when the form first appears"); - const formEntry = session.getBranch().at(-1)?.id; - assert.ok(formEntry); - host.type(KEY.enter); - - session.branch(formEntry); - host.emit("session_tree"); - await tick(); - assert.match(host.panelText(), /Which database\?/, "the form was rebuilt"); - assert.equal(bells(), 1, "a rebuilt form is not announced again"); - } finally { - writes.mock.restore(); - } -}); - -test("a blocking form's last keystrokes are journalled on shutdown", async () => { - const host = boot(); - await start(host, "startup"); - const pending = host.ask(TEXT_FORM); - pending.catch(() => {}); - await tick(); - mock.timers.enable({ apis: ["setTimeout"] }); - try { - host.forms[0]?.press(..."src/ui"); - assert.deepEqual(kinds(host), ["form"], "typing waits for the pause"); - // Pi quits before the typing timer fires. - host.emit("session_shutdown", { reason: "quit" }); - assert.deepEqual(kinds(host), ["form", "draft"]); - mock.timers.tick(5000); - } finally { - mock.timers.reset(); - } - assert.deepEqual(kinds(host), ["form", "draft"], "nothing is written twice"); - - const later = boot(host.session); - await start(later); - await later.command("ask-panel"); - assert.match(later.panelText(), /src\/ui/, "the unfinished answer came back"); -}); - -test("a finished blocking form is not flushed again on shutdown", async () => { - const host = boot(); - await start(host, "startup"); - const pending = host.ask(PARAMS); - await tick(); - host.forms[0]?.press(...SUBMIT_TWO); - await pending; - const before = kinds(host); - host.emit("session_shutdown", { reason: "quit" }); - assert.deepEqual(kinds(host), before); -}); diff --git a/pi-ask/tests/support/background.ts b/pi-ask/tests/support/background.ts new file mode 100644 index 00000000..d61eb888 --- /dev/null +++ b/pi-ask/tests/support/background.ts @@ -0,0 +1,102 @@ +import assert from "node:assert/strict"; +import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { registerAskTool } from "../../src/ask-tool.ts"; +import { registerAskBackground } from "../../src/background.ts"; +import { createAskRuntime } from "../../src/runtime.ts"; +import { fakePi, KEY, tick } from "./fake-pi.ts"; + +const question = (id: string, prompt: string, first: string, second: string) => ({ + id, + label: id.toUpperCase(), + prompt, + options: [ + { value: first.toLowerCase(), label: first }, + { value: second.toLowerCase(), label: second }, + ], +}); + +export const PARAMS = { + title: "Storage", + questions: [ + question("db", "Which database?", "Postgres", "SQLite"), + question("cache", "Which cache?", "Redis", "None"), + ], +}; +export const ONE = (id: string, title = id) => ({ + title, + questions: [question(id, `Pick ${id}?`, "Yes", "No")], +}); +/** Answer every question with its first option and submit. */ +export const SUBMIT_TWO = [KEY.enter, KEY.enter, KEY.enter]; +export const SUBMIT_ONE = [KEY.enter, KEY.enter]; + +/** One Pi process: the extension wired as `src/index.ts` wires it. */ +export function boot( + session?: SessionManager, + options: { + background?: boolean; + mode?: string; + persistToolResults?: boolean; + } = {} +) { + const host = fakePi(session, options); + const runtime = createAskRuntime(host.pi); + registerAskBackground(host.pi, runtime); + registerAskTool(host.pi, { + runtime, + features: { background: options.background ?? true, expiry: false }, + }); + let calls = 0; + const ask = (params: object = PARAMS) => + host.tools[0].execute(`call-${++calls}`, params, undefined, () => {}, host.ctx); + const askInBackground = (params: object = PARAMS) => + ask({ ...params, background: true }); + return { ...host, host, ask, askInBackground }; +} + +type Host = ReturnType; + +export async function start(host: Host, reason = "resume") { + host.emit("session_start", { reason }); + await tick(); +} + +export const kinds = (host: Host) => host.journal().map((entry) => entry.kind); +export const ids = (host: Host) => + host + .journal() + .filter((entry) => entry.kind === "form") + .map((entry) => entry.requestId); + +/** A session whose foreground form was open, DB answered, when Pi died. */ +export async function interruptedSession() { + const first = boot(); + first.ask().catch(() => {}); + await tick(); + first.forms[0]?.press(KEY.enter); + assert.deepEqual(kinds(first), ["form", "draft"]); + return first.session; +} + +/** A started process with one background form in the focused panel. */ +export async function withBackgroundForm(params: object = PARAMS) { + const host = boot(); + await start(host, "startup"); + const receipt = await host.askInBackground(params); + return { host, receipt, requestId: receipt.details.requestId as string }; +} + +/** + * A session whose blocking form was answered, but where Pi died before it + * wrote the tool result: the answer exists only in the journal. + */ +export async function unrecordedToolSession() { + const first = boot(undefined, { persistToolResults: false }); + const pending = first.ask(); + await tick(); + first.forms[0]?.press(...SUBMIT_TWO); + await pending; + assert.equal(first.journal().at(-1)?.channel, "tool"); + assert.equal(first.answers().length, 0); + return first.session; +} diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 18e08c58..a9aaa0cd 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,7 +2,7 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "background-panel.test.ts", "background-delivery.test.ts", "background-recovery.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled", "agent_start"], }, From 476b1056176be43b8535fd1e058b3081a53ea75f Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 00:53:53 +0000 Subject: [PATCH 32/38] fix(ask): retain panel controllers while temporarily hidden --- pi-ask/src/ui/panel.ts | 40 +++++++++++++++----------- pi-ask/tests/background-panel.test.ts | 41 ++++++++++++++++++++++++++- 2 files changed, 64 insertions(+), 17 deletions(-) diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts index 6a91452f..e209c946 100644 --- a/pi-ask/src/ui/panel.ts +++ b/pi-ask/src/ui/panel.ts @@ -79,7 +79,9 @@ export interface AskPanel { } export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { - let form: { component: AskFlowComponent; requestId: string } | undefined; + let form: + | { component: AskFlowComponent; requestId: string; ui: Ui } + | undefined; let mounted: { tui: FocusAwareTui; ui: Ui } | undefined; let returnFocus: TuiComponent = null; // True while this module moves focus itself, so the TUI's own blur @@ -177,16 +179,24 @@ export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { } } - function mount(ctx: ExtensionContext, next: AskPanelForm) { + function mount( + ctx: ExtensionContext, + requestId: string, + load: (requestId: string) => AskPanelForm | undefined + ) { const build = (tui: Tui, theme: Theme) => { mounted = { tui, ui: ctx.ui }; - if (form?.requestId !== next.requestId) { + if (form?.requestId !== requestId || form.ui !== ctx.ui) { unloadForm(); - form = { - requestId: next.requestId, - component: createPanelForm(ctx, tui, theme, next, callbacks), - }; - form.component.focused = focused; + const next = load(requestId); + if (next) { + form = { + requestId, + ui: ctx.ui, + component: createPanelForm(ctx, tui, theme, next, callbacks), + }; + form.component.focused = focused; + } } return shell; }; @@ -197,8 +207,7 @@ export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { return; } unmount(); - unloadForm(); - ctx.ui.setWidget(ASK_PANEL_WIDGET_KEY, build as never, { + ctx.ui.setWidget(ASK_PANEL_WIDGET_KEY, build, { placement: "aboveEditor", }); } @@ -214,12 +223,11 @@ export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { mounted.ui !== ctx.ui || form?.requestId !== view.formId ) { - const next = load(view.formId); - if (!next) { - unmount(); - return true; - } - mount(ctx, next); + mount(ctx, view.formId, load); + } + if (!form) { + unmount(); + return true; } if (!view.focused) { releaseFocus(); diff --git a/pi-ask/tests/background-panel.test.ts b/pi-ask/tests/background-panel.test.ts index 3cf7f72e..f4610f3e 100644 --- a/pi-ask/tests/background-panel.test.ts +++ b/pi-ask/tests/background-panel.test.ts @@ -1,5 +1,5 @@ import assert from "node:assert/strict"; -import test, { beforeEach } from "node:test"; +import test, { beforeEach, mock } from "node:test"; import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; import { boot, @@ -150,6 +150,45 @@ test("forms are shown one at a time in request order, across defer and reopen", // --- Ownership ------------------------------------------------------------- +test("a blocking form leaves pending background typing and its editor intact", async () => { + const { host } = await withBackgroundForm({ + questions: [{ id: "notes", prompt: "Write notes", type: "text" }], + }); + mock.timers.enable({ apis: ["setTimeout"] }); + try { + host.type(..."keep-me"); + assert.deepEqual(kinds(host), ["form"], "typing has not been flushed"); + const blocking = host.ask(ONE("urgent")); + // Let the modal open without advancing the draft debounce. + await new Promise((resolve) => setImmediate(resolve)); + host.forms.at(-1)?.press(...SUBMIT_ONE); + await blocking; + + assert.match(host.panelText(), /keep-me/); + host.type(..."-too", KEY.enter, KEY.enter); + assert.equal( + host.sent[0]?.message.details.result.answers.notes.customText, + "keep-me-too" + ); + } finally { + host.emit("session_shutdown"); + mock.timers.reset(); + } +}); + +test("hide and reopen retain the active option-note editor", async () => { + const { host } = await withBackgroundForm(ONE("choice")); + host.type("n", ..."first", KEY.later, KEY.focus); + assert.match(host.panelText(), /first/); + // Reopening must keep the note editor, not return to option navigation. + host.type(..." second", KEY.enter, ...SUBMIT_ONE); + assert.equal( + host.sent[0]?.message.details.result.answers.choice.optionNotes.yes, + "first second" + ); + host.emit("session_shutdown"); +}); + test("a blocking call takes the keyboard from an open background form and gives it back", async () => { const { host, requestId } = await withBackgroundForm(); host.type(KEY.enter); From ddb05281a37106f2a9368e19703d8ef5f6a5793e Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:01:36 +0000 Subject: [PATCH 33/38] fix(ask): require journal writes before acknowledging forms --- pi-ask/src/background.ts | 17 +++- pi-ask/src/journal/journal.ts | 25 ++++-- pi-ask/src/ui/controller.ts | 40 ++++++++-- pi-ask/tests/ask-tool.test.ts | 1 + pi-ask/tests/contract.test.ts | 1 + pi-ask/tests/expiry-flow.test.ts | 18 ++++- pi-ask/tests/journal-failure.test.ts | 112 +++++++++++++++++++++++++++ pi-ask/tests/rpc-flow.test.ts | 1 + scripts/packages.mjs | 2 +- 9 files changed, 198 insertions(+), 19 deletions(-) create mode 100644 pi-ask/tests/journal-failure.test.ts diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 22d7c964..1dcfffca 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -29,7 +29,7 @@ import { ASK_ANSWER_MESSAGE_TYPE, type AskFormSnapshot, } from "./journal/entries.ts"; -import { readAskJournal } from "./journal/journal.ts"; +import { AskJournalWriteError, readAskJournal } from "./journal/journal.ts"; import { type AskJournalRecord, getRecord, @@ -324,7 +324,14 @@ export function createAskBackground( createInitialState(formToParams(record.form)), record.draft ); - complete(requestId, toExpiredResult(formState)); + try { + complete(requestId, toExpiredResult(formState)); + } catch (error) { + if (!(error instanceof AskJournalWriteError)) { + throw error; + } + ctx?.ui.notify(error.message, "error"); + } } function dispatch(event: AskPanelEvent) { @@ -481,7 +488,11 @@ export function createAskBackground( delivery.pump(current); } } - } catch { + } catch (error) { + if (error instanceof AskJournalWriteError) { + // The input boundary reports this and keeps the form open to retry. + throw error; + } // A stale context: nothing is written. } releaseTimer(requestId); diff --git a/pi-ask/src/journal/journal.ts b/pi-ask/src/journal/journal.ts index 05933354..cf4bd372 100644 --- a/pi-ask/src/journal/journal.ts +++ b/pi-ask/src/journal/journal.ts @@ -101,8 +101,8 @@ export function createAskJournal( if (key === lastKey) { return; } - lastKey = key; write({ kind: "draft", requestId, draft }); + lastKey = key; }; }, recordDefer(requestId) { @@ -130,19 +130,28 @@ export function createAskJournal( }; } -/** - * Journal backed by the session file. Writing is best-effort: a host without - * `appendEntry`, or a failed write, must not stop the user being asked. - */ +/** A failed journal append must never be mistaken for an accepted form. */ +export class AskJournalWriteError extends Error { + constructor(entry: AskJournalEntry, cause: unknown) { + const detail = cause instanceof Error ? cause.message : String(cause); + super( + `Could not save ask_user ${entry.kind} (${entry.requestId}): ${detail}. Nothing was acknowledged; fix session storage and retry.`, + { cause } + ); + this.name = "AskJournalWriteError"; + } +} + +/** Journal backed by the session file; successful writes are required. */ export function createSessionAskJournal( pi: Pick, deps?: AskJournalDeps ): AskJournal { return createAskJournal((entry) => { try { - pi.appendEntry?.(ASK_JOURNAL_ENTRY_TYPE, entry); - } catch { - // Losing recovery data is better than losing the question. + pi.appendEntry(ASK_JOURNAL_ENTRY_TYPE, entry); + } catch (error) { + throw new AskJournalWriteError(entry, error); } }, deps); } diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 50a72d30..8429bc66 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -9,6 +9,7 @@ import { notifyQuestionWaiting, } from "../notifications.ts"; import type { AskDraftSnapshot } from "../journal/entries.ts"; +import { AskJournalWriteError } from "../journal/journal.ts"; import { createInitialState } from "../state/create.ts"; import { type ExpiryTimer, toExpiredResult } from "../state/expiry.ts"; import { applyDraftSnapshot } from "../state/draft.ts"; @@ -204,8 +205,14 @@ export function createAskFlowController( ctx: params.ctx, done: (result) => { controller.finished = true; + try { + done(result); + } catch (error) { + controller.finished = false; + reportJournalError(controller, error); + return; + } unregisterFlush(); - done(result); }, editor: createEditor(tui, theme, params.cwd), expiry: params.expiry?.timer, @@ -272,10 +279,14 @@ export function createAskFlowController( controller.editor.invalidate(); }, handleInput(data: string) { - // One key means the user is here: the countdown ends for good. - controller.expiry?.interact(); - controller.onInput?.(data); - handleControllerInput(controller, data); + try { + // One key means the user is here: the countdown ends for good. + controller.expiry?.interact(); + controller.onInput?.(data); + handleControllerInput(controller, data); + } catch (error) { + reportJournalError(controller, error); + } }, detach() { cancelDraftTimer(controller); @@ -309,10 +320,27 @@ function cancelDraftTimer(controller: AskFlowController) { function flushDraft(controller: AskFlowController) { cancelDraftTimer(controller); if (!controller.finished) { - controller.onStateChange?.(snapshotState(controller)); + try { + controller.onStateChange?.(snapshotState(controller)); + } catch (error) { + reportJournalError(controller, error); + } } } +/** Storage failures keep the live form editable and its submission retryable. */ +function reportJournalError(controller: AskFlowController, error: unknown) { + if (!(error instanceof AskJournalWriteError)) { + throw error; + } + controller.state = { ...controller.state, completed: false, cancelled: false }; + if (controller.statusNotice !== error.message) { + controller.ctx.ui.notify(error.message, "error"); + } + controller.statusNotice = error.message; + controller.tui.requestRender(); +} + /** Keystrokes in an editor are reported once typing pauses, not one by one. */ function scheduleDraft(controller: AskFlowController) { if (!controller.onStateChange) { diff --git a/pi-ask/tests/ask-tool.test.ts b/pi-ask/tests/ask-tool.test.ts index a042e323..fe2ff86a 100644 --- a/pi-ask/tests/ask-tool.test.ts +++ b/pi-ask/tests/ask-tool.test.ts @@ -21,6 +21,7 @@ const INVALID_TYPE_RE = function registerMockTool() { const tools: Record[] = []; registerAskTool({ + appendEntry() {}, registerTool(tool: unknown) { tools.push(tool as Record); }, diff --git a/pi-ask/tests/contract.test.ts b/pi-ask/tests/contract.test.ts index ba4589f6..2b33a676 100644 --- a/pi-ask/tests/contract.test.ts +++ b/pi-ask/tests/contract.test.ts @@ -22,6 +22,7 @@ import type { AskParams, AskResult } from "../src/types.ts"; function registerMockTool() { const tools: Record[] = []; registerAskTool({ + appendEntry() {}, registerTool(tool: unknown) { tools.push(tool as Record); }, diff --git a/pi-ask/tests/expiry-flow.test.ts b/pi-ask/tests/expiry-flow.test.ts index 3da75890..30a0899b 100644 --- a/pi-ask/tests/expiry-flow.test.ts +++ b/pi-ask/tests/expiry-flow.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import test, { beforeEach } from "node:test"; -import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { type ExtensionAPI, SessionManager } from "@earendil-works/pi-coding-agent"; import { registerAskTool } from "../src/ask-tool.ts"; import { EXPIRED_OFFER_MS, registerAskBackground } from "../src/background.ts"; import { DEFAULT_ASK_CONFIG } from "../src/config/defaults.ts"; @@ -79,6 +79,22 @@ async function withTimedPanel(params: object = TIMED) { beforeEach(quietConfig); +test("an expiry whose outcome cannot be saved stays open for a manual answer", async (t) => { + const { host } = await withTimedPanel(); + const pi: ExtensionAPI = host.pi; + const failure = t.mock.method(pi, "appendEntry", () => { throw new Error("disk full"); }); + host.time.advance(60 * SECOND); + assert.equal(outcomes(host).length, 0); + assert.equal(host.sent.length, 0); + assert.match(host.notices.at(-1) ?? "", /Could not save ask_user outcome/); + + failure.mock.restore(); + host.type(KEY.enter, KEY.enter, KEY.enter); + assert.equal(host.sent[0]?.message.details.result.status, "submitted"); + assert.deepEqual(host.sent[0]?.message.details.result.answers.db.values, ["pg"]); + host.emit("session_shutdown"); +}); + // --- Blocking forms -------------------------------------------------------- test("a blocking form counts down on screen and expires to its declared fallback", async () => { diff --git a/pi-ask/tests/journal-failure.test.ts b/pi-ask/tests/journal-failure.test.ts new file mode 100644 index 00000000..00c8d80d --- /dev/null +++ b/pi-ask/tests/journal-failure.test.ts @@ -0,0 +1,112 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; +import type { AskJournalEntry } from "../src/journal/entries.ts"; +import { AskJournalWriteError, createAskJournal } from "../src/journal/journal.ts"; +import { createInitialState } from "../src/state/create.ts"; +import { boot, kinds, ONE, SUBMIT_ONE, SUBMIT_TWO, withBackgroundForm } from "./support/background.ts"; +import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; + +beforeEach(quietConfig); + +for (const background of [false, true]) { + test(`a failed form append rejects a ${background ? "background" : "blocking"} call before acknowledging it`, async (t) => { + const host = boot(); + const pi: ExtensionAPI = host.pi; + t.mock.method(pi, "appendEntry", () => { throw new Error("disk full"); }); + + await assert.rejects(host.ask({ ...ONE("choice"), background }), AskJournalWriteError); + assert.deepEqual(kinds(host), []); + assert.equal(host.forms.length, 0); + assert.equal(host.panelText(), ""); + assert.deepEqual(host.sent, []); + host.emit("session_shutdown"); + }); +} + +test("a failed background outcome stays editable and can be submitted again", async (t) => { + const { host } = await withBackgroundForm(); + const pi: ExtensionAPI = host.pi; + const append = pi.appendEntry; + const failure = t.mock.method(pi, "appendEntry", (type: string, data: unknown) => { + if ((data as AskJournalEntry).kind === "outcome") { + throw new Error("disk full"); + } + append(type, data); + }); + + host.type(...SUBMIT_TWO); + assert.equal(host.sent.length, 0); + assert.deepEqual(kinds(host), ["form", "draft", "draft"]); + assert.match(host.notices.at(-1) ?? "", /Could not save ask_user outcome.*disk full/); + assert.match(host.panelText(), /Could not save ask_user outcome/); + + failure.mock.restore(); + host.type(KEY.enter); + assert.equal(host.sent.length, 1); + assert.deepEqual(host.sent[0].message.details.result.answers.db.values, ["postgres"]); + assert.deepEqual(host.sent[0].message.details.result.answers.cache.values, ["redis"]); + assert.equal(kinds(host).filter((kind) => kind === "outcome").length, 1); + host.emit("session_shutdown"); +}); + +test("a failed foreground outcome rejects the tool result instead of returning an answer", async (t) => { + const host = boot(); + const pi: ExtensionAPI = host.pi; + const append = pi.appendEntry; + t.mock.method(pi, "appendEntry", (type: string, data: unknown) => { + if ((data as AskJournalEntry).kind === "outcome") { + throw new Error("disk full"); + } + append(type, data); + }); + const rejected = assert.rejects(host.ask(ONE("choice")), AskJournalWriteError); + await tick(); + host.forms[0]?.press(...SUBMIT_ONE); + await rejected; + assert.equal(kinds(host).includes("outcome"), false); + assert.equal(host.answers().length, 0); + host.emit("session_shutdown"); +}); + +test("a failed debounced draft reports the error and retains the typed answer for retry", async (t) => { + const { host } = await withBackgroundForm({ + questions: [{ id: "notes", prompt: "Notes?", type: "text" }], + }); + const pi: ExtensionAPI = host.pi; + const append = pi.appendEntry; + const failure = t.mock.method(pi, "appendEntry", (type: string, data: unknown) => { + if ((data as AskJournalEntry).kind === "draft") { + throw new Error("disk full"); + } + append(type, data); + }); + t.mock.timers.enable({ apis: ["setTimeout"] }); + host.type(..."keep this"); + t.mock.timers.tick(1000); + assert.match(host.notices.at(-1) ?? "", /Could not save ask_user draft/); + assert.match(host.panelText(), /keep this/); + assert.deepEqual(kinds(host), ["form"]); + + failure.mock.restore(); + host.type(KEY.enter, KEY.enter); + assert.equal(host.sent[0]?.message.details.result.answers.notes.customText, "keep this"); + assert.deepEqual(kinds(host), ["form", "draft", "outcome"]); + host.emit("session_shutdown"); +}); + +test("draft deduplication advances only after a successful write", () => { + let writes = 0; + const journal = createAskJournal(() => { + if (++writes === 1) { + throw new Error("disk full"); + } + }); + const record = journal.draftRecorder("ask-retry"); + const state = createInitialState({ questions: [{ id: "notes", prompt: "Notes?", type: "text" }] }); + state.answers.notes = { selected: [], customText: "same draft", customSelected: true }; + assert.throws(() => record(state), /disk full/); + record(state); + record(state); + assert.equal(writes, 2, "the failed write is retried, then deduplicated"); +}); diff --git a/pi-ask/tests/rpc-flow.test.ts b/pi-ask/tests/rpc-flow.test.ts index f4c6f4e2..da299282 100644 --- a/pi-ask/tests/rpc-flow.test.ts +++ b/pi-ask/tests/rpc-flow.test.ts @@ -316,6 +316,7 @@ test("zh locale renders localized rows and summaries", async () => { function registerMockTool() { const tools: Array> = []; registerAskTool({ + appendEntry() {}, registerTool(tool: unknown) { tools.push(tool as Record); }, diff --git a/scripts/packages.mjs b/scripts/packages.mjs index a9aaa0cd..55925944 100644 --- a/scripts/packages.mjs +++ b/scripts/packages.mjs @@ -2,7 +2,7 @@ export const packages = { "pi-ask": { name: "@gagansd/pi-ask", tests: "tests", - integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "background-panel.test.ts", "background-delivery.test.ts", "background-recovery.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], + integration: ["contract.test.ts", "ask-tool.test.ts", "answer-commands.test.ts", "config-store.test.ts", "token-ceiling.test.ts", "background.test.ts", "background-panel.test.ts", "background-delivery.test.ts", "background-recovery.test.ts", "journal-failure.test.ts", "expiry-flow.test.ts", "skip-cancel-flow.test.ts"], commands: ["answer", "ask-settings", "ask-panel"], tools: ["ask_user"], hooks: ["session_start", "session_tree", "session_shutdown", "session_compact", "turn_end", "agent_before_settle", "agent_settled", "agent_start"], }, From e6091dc7d95b9143672a7a81d92b0572cf2faf0f Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:04:03 +0000 Subject: [PATCH 34/38] fix(ask): retain adopted outcomes until branch-proven delivery --- pi-ask/src/background.ts | 17 ++--- pi-ask/src/delivery.ts | 83 ++++++++---------------- pi-ask/tests/background-delivery.test.ts | 56 ++++++++++++++++ 3 files changed, 88 insertions(+), 68 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 1dcfffca..fa7ac36e 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -115,7 +115,7 @@ export interface AskBackground { /** The agent run is over; `aborted` when the user stopped it. */ settled(ctx: ExtensionContext, aborted?: boolean): void; /** A run started: sends that never reached the branch are retried. */ - started(ctx: ExtensionContext): void; + started(): void; } export function registerAskBackground( @@ -128,7 +128,7 @@ export function registerAskBackground( pi.on("session_start", (_event, ctx) => background.attach(ctx)); pi.on("session_tree", (_event, ctx) => background.attach(ctx)); pi.on("session_shutdown", () => background.dispose()); - pi.on("agent_start", (_event, ctx) => background.started(ctx)); + pi.on("agent_start", () => background.started()); pi.on("turn_end", (event, ctx) => background.boundary(ctx, event) as never); pi.on( "agent_before_settle", @@ -584,7 +584,7 @@ export function createAskBackground( } reconcileBranch(next); refresh((queue, hidden) => ({ type: "sync", queue, hidden })); - delivery.attach(); + delivery.attach(next); poke(next); }, poke, @@ -672,14 +672,9 @@ export function createAskBackground( // A stale context: the next event tries again. } }, - started(next) { - if (disposed) { - return; - } - try { - delivery.started(next); - } catch { - // A stale context: the next event tries again. + started() { + if (!disposed) { + delivery.started(); } }, dispose() { diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index 2c52fe9a..efc91db4 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -5,8 +5,8 @@ * * Exactly-once rests on the session branch. An outcome is delivered when its * `pi-ask:answer` message is on the branch; until then it is pending. The - * only in-memory state is the set of outcomes sent and not yet seen there, - * which keeps a message that is still on its way from being sent again. + * process-local state identifies orphaned tool outcomes adopted on attach + * and sends still in flight, so messages on their way are not sent twice. * How a pending outcome is sent is decided in `state/outbox.ts`. */ import type { @@ -60,12 +60,12 @@ export interface AskDelivery { * The branch was (re)built. A foreground answer whose tool result never * landed is adopted as a follow-up message, once. */ - attach(): void; + attach(ctx: DeliveryContext): void; /** * A run started. A send the branch still lacks never made it into a run, * so the answer is no longer held back; the next pump retries it. */ - started(ctx: DeliveryContext): void; + started(): void; /** Deliver what can be delivered now. `settled`: the run is over. */ pump( ctx: DeliveryContext, @@ -172,28 +172,25 @@ function answerMessage(outcome: AskOutcomeEntry) { export function createAskDelivery( pi: Pick ): AskDelivery { - // Sent in this process, not yet on the branch. Never cleared on a timer or - // a lifecycle event: a second send is the one thing that must not happen. + // Sent in this process, potentially still being written by a run. Cleared + // only when idle or a new run starts; the branch then proves delivery. const inFlight = new Set(); // False while the branch is known to have nothing pending, so that turn // boundaries of an ordinary run cost nothing. let watching = true; - // The next plan was reached by rebuilding a session, where a foreground - // answer without its tool result can be adopted as a message. - let recovering = false; + // Only tool outcomes already orphaned at attach can become messages. + // Eligibility lasts until branch evidence proves delivery, not one plan. + let adopted = new Set(); function plan(ctx: DeliveryContext, situation: AskDeliverySituation) { if (!watching) { return; } const pending = undeliveredOutcomes(readAskJournal(ctx), { - unrecordedTool: recovering, - }); - // Only a plan that can act on an adopted answer clears the adoption. One - // that can only hold it leaves the next plan able to adopt and send it. - if (situation.trigger !== "now" || situation.idle) { - recovering = false; - } + unrecordedTool: true, + }).filter( + ({ outcome }) => outcome.channel === "message" || adopted.has(outcome.outcomeId) + ); if (pending.length === 0) { watching = false; return; @@ -224,56 +221,28 @@ export function createAskDelivery( } } - /** - * Forgets sends the branch still shows as pending. Pi's `sendMessage` is - * fire-and-forget: when the run it starts fails before recording the - * message, nothing lands and nothing reports the failure. Left in flight, - * that answer would be held for the rest of the process. Only called when - * no run can still be writing the message (the host is idle, or a run just - * started): the branch itself is the proof of what was delivered. - */ - function release(ctx: DeliveryContext) { - if (inFlight.size === 0) { - return; - } - // An adopted tool outcome counts here too: neither call site has a live - // call that could still be writing its result, so the branch proves it - // was never sent. - const pending = new Map( - undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true }).map( - ({ outcome }) => [outcome.outcomeId, outcome] - ) - ); - for (const outcomeId of [...inFlight]) { - const outcome = pending.get(outcomeId); - if (!outcome) { - continue; - } - inFlight.delete(outcomeId); - // The adopted answer never reached the branch, so adopt it again and - // let the next plan retry it in this process. - if (outcome.channel === "tool") { - recovering = true; - } - } - } - return { post() { watching = true; }, - attach() { + attach(ctx) { + adopted = new Set( + undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true }) + .filter(({ outcome }) => outcome.channel === "tool") + .map(({ outcome }) => outcome.outcomeId) + ); watching = true; - recovering = true; }, - started(ctx) { - // A run that did start has not recorded its own starting message - // yet, so do not send here: the next boundary sees it on the branch. - release(ctx); + started() { + // No prior run can still be writing a send. Do not send here: this + // run's starting message is recorded before its first boundary. + inFlight.clear(); }, pump(ctx, situation = {}) { if (ctx.isIdle()) { - release(ctx); + // Nothing can still be writing a send: retry anything the branch + // lacks, including a wake whose run never started. + inFlight.clear(); } const planned = plan(ctx, { trigger: situation.trigger ?? "now", diff --git a/pi-ask/tests/background-delivery.test.ts b/pi-ask/tests/background-delivery.test.ts index a0982dc6..efd556bc 100644 --- a/pi-ask/tests/background-delivery.test.ts +++ b/pi-ask/tests/background-delivery.test.ts @@ -1,5 +1,6 @@ import assert from "node:assert/strict"; import test, { beforeEach } from "node:test"; +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { ASK_ANSWER_MESSAGE_TYPE } from "../src/journal/entries.ts"; import { KEY, quietConfig, tick } from "./support/fake-pi.ts"; import { @@ -7,6 +8,7 @@ import { start, kinds, ONE, + SUBMIT_ONE, SUBMIT_TWO, withBackgroundForm, unrecordedToolSession, @@ -16,6 +18,60 @@ beforeEach(quietConfig); // --- Delivery -------------------------------------------------------------- +test("an adopted tool answer retries synchronous send failures until delivered once", async (t) => { + const host = boot(await unrecordedToolSession()); + const pi: ExtensionAPI = host.pi; + const send = pi.sendMessage; + let attempts = 0; + t.mock.method(pi, "sendMessage", (...args: Parameters) => { + if (++attempts <= 2) { + throw new Error("send unavailable"); + } + send(...args); + }); + + await start(host); + assert.equal(attempts, 1); + host.settle(); + assert.equal(attempts, 2); + assert.equal(host.sent.length, 0); + host.settle(); + assert.equal(attempts, 3); + assert.equal(host.sent.length, 1); + host.recordWake(); + host.settle(); + await start(host, "reload"); + assert.equal(attempts, 3); + assert.equal(host.answers().length, 1); + host.emit("session_shutdown"); +}); + +test("adoption keeps every orphaned tool answer eligible across delivery plans", async () => { + const first = boot(undefined, { persistToolResults: false }); + for (const id of ["a", "b"]) { + const pending = first.ask(ONE(id)); + await tick(); + first.forms.at(-1)?.press(...SUBMIT_ONE); + await pending; + } + first.emit("session_shutdown"); + + const host = boot(first.session); + await start(host); + assert.equal(host.sent.length, 1, "only the first answer wakes the agent"); + host.recordWake(); + const boundary = host.turnEnd(); + assert.equal(boundary.entries.length, 1, "the held answer joins the running turn"); + assert.equal(host.answers().length, 2); + assert.equal(boundary.continue, true); + assert.deepEqual(host.turnEnd(), { entries: [], continue: false }); + host.settle(); + await start(host, "reload"); + assert.equal(host.answers().length, 2); + assert.equal(host.sent.length, 1); + host.emit("session_shutdown"); +}); + test("an idle agent is woken by the answer, which names the form and each question", async () => { const { host, requestId } = await withBackgroundForm(); host.type(...SUBMIT_TWO); From d86bfff72e1c653dc16433a80fae77169b94f5c5 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:07:09 +0000 Subject: [PATCH 35/38] refactor(ask): use canonical host boundary contracts --- pi-ask/src/background.ts | 10 ++--- pi-ask/src/delivery.ts | 54 ++++++++---------------- pi-ask/src/state/outbox.ts | 16 ------- pi-ask/tests/background-delivery.test.ts | 28 +++++++++--- pi-ask/tests/outbox.test.ts | 15 ------- pi-ask/tests/support/fake-pi.ts | 30 ++++++++----- 6 files changed, 65 insertions(+), 88 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index fa7ac36e..92742107 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -9,6 +9,7 @@ * wiring; the rules live in `state/panel.ts` and `state/outbox.ts`. */ import type { + BoundaryResult, ExtensionAPI, ExtensionCommandContext, ExtensionContext, @@ -20,7 +21,6 @@ import { getAskConfigStore } from "./config/store.ts"; import { getGlobalBindings, matchesBinding } from "./constants/keymaps.ts"; import { type AskBoundaryEvent, - type AskBoundaryResult, createAskDelivery, renderAskAnswerMessage, } from "./delivery.ts"; @@ -85,7 +85,7 @@ export interface AskBackground { boundary( ctx: ExtensionContext, event: AskBoundaryEvent - ): AskBoundaryResult | undefined; + ): BoundaryResult | undefined; /** Stop for good: the runtime this belongs to is going away. */ dispose(): void; /** @@ -129,10 +129,10 @@ export function registerAskBackground( pi.on("session_tree", (_event, ctx) => background.attach(ctx)); pi.on("session_shutdown", () => background.dispose()); pi.on("agent_start", () => background.started()); - pi.on("turn_end", (event, ctx) => background.boundary(ctx, event) as never); + pi.on("turn_end", (event, ctx) => background.boundary(ctx, event)); pi.on( "agent_before_settle", - (event, ctx) => background.boundary(ctx, event) as never + (event, ctx) => background.boundary(ctx, event) ); pi.on("agent_settled", (event, ctx) => background.settled(ctx, event.aborted) @@ -141,7 +141,7 @@ export function registerAskBackground( pi.on("session_compact", (_event, ctx) => background.poke(ctx)); pi.registerMessageRenderer?.( ASK_ANSWER_MESSAGE_TYPE, - renderAskAnswerMessage as never + renderAskAnswerMessage ); pi.registerCommand?.("ask-panel", { description: "Show waiting ask_user questions", diff --git a/pi-ask/src/delivery.ts b/pi-ask/src/delivery.ts index efc91db4..6d76faa6 100644 --- a/pi-ask/src/delivery.ts +++ b/pi-ask/src/delivery.ts @@ -10,8 +10,12 @@ * How a pending outcome is sent is decided in `state/outbox.ts`. */ import type { + BoundaryResult, + BoundaryState, + CustomMessageEntryDraft, ExtensionAPI, ExtensionContext, + MessageRenderer, } from "@earendil-works/pi-coding-agent"; import { Text } from "@earendil-works/pi-tui"; import { askStrings } from "./i18n.ts"; @@ -26,7 +30,6 @@ import { renderResultText } from "./result.ts"; import { type AskDeliverySituation, type AskDeliveryStep, - boundaryContinues, planDelivery, } from "./state/outbox.ts"; import type { AskResult, AskResultAnswer } from "./types.ts"; @@ -34,16 +37,7 @@ import type { AskResult, AskResultAnswer } from "./types.ts"; type DeliveryContext = Pick; /** The part of a `turn_end` / `agent_before_settle` event that is read. */ -export interface AskBoundaryEvent { - entries?: readonly unknown[]; - message?: unknown; -} - -/** What Pi appends at the boundary; shaped as its `custom_message` draft. */ -export interface AskBoundaryResult { - continue?: boolean; - entries: unknown[]; -} +export type AskBoundaryEvent = Pick; export interface AskDelivery { /** @@ -53,7 +47,7 @@ export interface AskDelivery { boundary( ctx: DeliveryContext, event: AskBoundaryEvent - ): AskBoundaryResult | undefined; + ): BoundaryResult | undefined; /** An outcome was just journalled with channel `message`. */ post(): void; /** @@ -268,39 +262,27 @@ export function createAskDelivery( // Not marked in flight: Pi appends these as soon as the handlers // return, so the branch itself answers the next check. const entries = [ - ...(event.entries ?? []), - ...proposed.map((outcome) => ({ + ...event.entries, + ...proposed.map((outcome): CustomMessageEntryDraft => ({ type: "custom_message", ...answerMessage(outcome), })), ]; - const wantsTurn = boundaryContinues( - proposed.map((outcome) => ({ - cancelled: outcome.result.status === "cancelled", - })), - stopReason(event.message) - ); + const wantsTurn = + event.outcome === "completed" && + proposed.some((outcome) => outcome.result.status !== "cancelled"); return wantsTurn ? { entries, continue: true } : { entries }; }, }; } -function stopReason(message: unknown): string | undefined { - const reason = (message as { stopReason?: unknown } | undefined)?.stopReason; - return typeof reason === "string" ? reason : undefined; -} - -type MessageTheme = ExtensionContext["ui"]["theme"]; - /** Transcript card for a delivered answer, in place of the raw message. */ -export function renderAskAnswerMessage( - message: { details?: unknown }, - _options: unknown, - theme: MessageTheme -) { - const details = message.details as - | Partial - | undefined; +export const renderAskAnswerMessage: MessageRenderer = ( + message, + _options, + theme +) => { + const details = message.details; const result = details?.result; if (!(result && Array.isArray(result.questions))) { return; @@ -327,4 +309,4 @@ export function renderAskAnswerMessage( 1, 0 ); -} +}; diff --git a/pi-ask/src/state/outbox.ts b/pi-ask/src/state/outbox.ts index 72908594..c0257543 100644 --- a/pi-ask/src/state/outbox.ts +++ b/pi-ask/src/state/outbox.ts @@ -74,19 +74,3 @@ export function planDelivery( return step("wake"); }); } - -/** - * Whether proposing at a boundary should also ask Pi for one more model - * request. Without it an answer that arrives during the final turn would sit - * in the conversation unseen. Cancellations never ask; neither does a turn - * the user aborted. - */ -export function boundaryContinues( - items: readonly Pick[], - turnStopReason?: string -): boolean { - if (turnStopReason === "aborted" || turnStopReason === "error") { - return false; - } - return items.some((item) => !item.cancelled); -} diff --git a/pi-ask/tests/background-delivery.test.ts b/pi-ask/tests/background-delivery.test.ts index efd556bc..83c9a2ff 100644 --- a/pi-ask/tests/background-delivery.test.ts +++ b/pi-ask/tests/background-delivery.test.ts @@ -18,6 +18,21 @@ beforeEach(quietConfig); // --- Delivery -------------------------------------------------------------- +for (const boundary of ["turnEnd", "beforeSettle"] as const) { + for (const outcome of ["completed", "aborted", "error"] as const) { + test(`${boundary} delivers an answer but continues only a completed run (${outcome})`, async () => { + const { host } = await withBackgroundForm(); + host.setIdle(false); + host.type(...SUBMIT_TWO); + const result = host[boundary](outcome); + assert.equal(result.entries.length, 1); + assert.equal(result.continue, outcome === "completed"); + assert.equal(host.sent.length, 0); + host.emit("session_shutdown"); + }); + } +} + test("an adopted tool answer retries synchronous send failures until delivered once", async (t) => { const host = boot(await unrecordedToolSession()); const pi: ExtensionAPI = host.pi; @@ -173,7 +188,7 @@ test("a new run releases an answer whose wake never started, and delivers it onc host.emit("agent_start"); const boundary = host.turnEnd(); assert.equal(boundary.entries.length, 1); - assert.equal(boundary.entries[0].details.requestId, requestId); + assert.equal(host.answers()[0].details.requestId, requestId); host.settle(); await start(host, "reload"); assert.equal(host.answers().length, 1); @@ -192,7 +207,8 @@ test("a working agent gets the answer at the next turn boundary, once, with no e assert.equal(first.entries.length, 1); assert.equal(first.entries[0].type, "custom_message"); assert.equal(first.entries[0].customType, ASK_ANSWER_MESSAGE_TYPE); - assert.equal(first.entries[0].details.requestId, requestId); + assert.equal(host.answers()[0].details.requestId, requestId); + assert.ok(typeof first.entries[0].content === "string"); assert.match(first.entries[0].content, /db "Which database\?": Postgres/); // Turn boundary, then settle: the same answer is not offered or sent again. @@ -223,7 +239,7 @@ test("boundary entries from other extensions are kept", async () => { host.setIdle(false); host.type(...SUBMIT_TWO); const other = { type: "custom", customType: "other", data: 1 }; - const [result] = host.emit("turn_end", { entries: [other], message: {} }) as any[]; + const [result] = host.emit("turn_end", { entries: [other], outcome: "completed" }) as any[]; assert.equal(result.entries.length, 2); assert.equal(result.entries[0], other); }); @@ -240,7 +256,7 @@ test("an answer left over after the user aborts is added without restarting the const { host: second } = await withBackgroundForm(); second.setIdle(false); second.type(...SUBMIT_TWO); - const boundary = second.turnEnd({ stopReason: "aborted" }); + const boundary = second.turnEnd("aborted"); assert.equal(boundary.entries.length, 1); assert.equal(boundary.continue, false); @@ -386,9 +402,11 @@ test("a cancellation while the agent works joins the turn boundary without askin assert.deepEqual(host.sent, []); assert.equal(host.aborts, 0); - const boundary = host.turnEnd({ stopReason: "stop" }); + const boundary = host.turnEnd(); assert.equal(boundary.entries.length, 1); assert.equal(boundary.continue, false); + assert.equal(boundary.entries[0].type, "custom_message"); + assert.ok(typeof boundary.entries[0].content === "string"); assert.match(boundary.entries[0].content, /cancelled/); }); diff --git a/pi-ask/tests/outbox.test.ts b/pi-ask/tests/outbox.test.ts index 547d752b..e9be8ab8 100644 --- a/pi-ask/tests/outbox.test.ts +++ b/pi-ask/tests/outbox.test.ts @@ -3,7 +3,6 @@ import test from "node:test"; import { formatDeliveredOutcome } from "../src/delivery.ts"; import { type AskDeliveryItem, - boundaryContinues, planDelivery, } from "../src/state/outbox.ts"; import type { AskResult } from "../src/types.ts"; @@ -37,7 +36,6 @@ test("a cancellation never wakes: appended when idle, proposed at a boundary", ( assert.deepEqual(actions(cancelled, { trigger: "boundary", idle: false }), [ "propose", ]); - assert.equal(boundaryContinues(cancelled), false); }); test("an outcome already on its way is never sent again, whatever happens next", () => { @@ -71,19 +69,6 @@ test("one wake per batch, in request order; the rest join at its first boundary" ]); }); -test("an answer at a boundary asks for one more request, unless the turn was aborted or failed", () => { - assert.equal(boundaryContinues([item("a")]), true); - assert.equal(boundaryContinues([item("a")], "stop"), true); - assert.equal(boundaryContinues([item("a")], "toolUse"), true); - assert.equal(boundaryContinues([item("a")], "aborted"), false); - assert.equal(boundaryContinues([item("a")], "error"), false); - assert.equal( - boundaryContinues([item("c", { cancelled: true }), item("a")]), - true - ); - assert.equal(boundaryContinues([]), false); -}); - const RESULT: AskResult = { title: "Storage", status: "submitted", diff --git a/pi-ask/tests/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts index df5954bf..9cb848c5 100644 --- a/pi-ask/tests/support/fake-pi.ts +++ b/pi-ask/tests/support/fake-pi.ts @@ -13,7 +13,14 @@ * - A widget is a component above or below the editor; it gets keys only * while it has TUI focus. A modal form takes focus and gives it back. */ -import { SessionManager } from "@earendil-works/pi-coding-agent"; +import { + type AgentActivityOutcome, + type BoundaryResult, + type BoundaryState, + type CustomMessageEntryDraft, + type SessionBoundaryDraft, + SessionManager, +} from "@earendil-works/pi-coding-agent"; import { DEFAULT_ASK_CONFIG } from "../../src/config/defaults.ts"; import { getAskConfigStore } from "../../src/config/store.ts"; import { ASK_JOURNAL_ENTRY_TYPE } from "../../src/journal/entries.ts"; @@ -120,7 +127,7 @@ export function fakePi( bold: (text: string) => text, }; - function persist(message: SentMessage["message"]) { + function persist(message: SentMessage["message"] | CustomMessageEntryDraft) { if (options.persistSentMessages === false) { return; } @@ -257,14 +264,14 @@ export function fakePi( } /** An actionable boundary: handlers chain entries, Pi appends them. */ - function boundary(event: string, payload: Record = {}) { - let entries: any[] = []; + function boundary(event: string, outcome: AgentActivityOutcome) { + let entries: SessionBoundaryDraft[] = []; let proceed = false; for (const handler of handlers.get(event) ?? []) { - const result = handler( - { type: event, ...payload, entries, continue: proceed }, - ctx - ) as { entries?: any[]; continue?: boolean } | undefined; + const state: Pick = { + entries, continue: proceed, outcome, + }; + const result = handler({ type: event, ...state }, ctx) as BoundaryResult | undefined; entries = result?.entries ?? entries; proceed = result?.continue ?? proceed; } @@ -310,9 +317,10 @@ export function fakePi( persist(message); } }, - turnEnd: (message: Record = { stopReason: "toolUse" }) => - boundary("turn_end", { message }), - beforeSettle: () => boundary("agent_before_settle"), + turnEnd: (outcome: AgentActivityOutcome = "completed") => + boundary("turn_end", outcome), + beforeSettle: (outcome: AgentActivityOutcome = "completed") => + boundary("agent_before_settle", outcome), /** The run is over: Pi is idle and tells the extensions. */ settle(aborted = false) { idle = true; From 9ed4b6e1fb6840b66760530c7f4176308a6287a5 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:08:04 +0000 Subject: [PATCH 36/38] refactor(ask): remove the redundant shipped-feature mask --- pi-ask/scripts/token-report.mjs | 10 +++----- pi-ask/src/features.ts | 21 ++++------------ pi-ask/tests/token-ceiling.test.ts | 40 +++++++++--------------------- 3 files changed, 21 insertions(+), 50 deletions(-) diff --git a/pi-ask/scripts/token-report.mjs b/pi-ask/scripts/token-report.mjs index 94941ae5..34c45864 100644 --- a/pi-ask/scripts/token-report.mjs +++ b/pi-ask/scripts/token-report.mjs @@ -3,20 +3,18 @@ * Measuring lives in ./footprint.ts, shared with the token-ceiling test. * Run with `npm run tokens`. */ -import { ALL_ASK_FEATURES, SHIPPED_ASK_FEATURES } from "../src/features.ts"; +import { ALL_ASK_FEATURES } from "../src/features.ts"; import { measureAskToolFootprint } from "./footprint.ts"; const row = (name, chars, tokens) => console.log(` ${name.padEnd(16)} ${String(chars).padStart(5)} / ${tokens}`); -const shipped = measureAskToolFootprint({ features: SHIPPED_ASK_FEATURES }); +const all = measureAskToolFootprint({ features: ALL_ASK_FEATURES }); console.log("ask_user context footprint (chars / est. tokens)"); -for (const part of shipped.parts) { +for (const part of all.parts) { row(part.name, part.chars, part.tokens); } -row("total", shipped.totalChars, shipped.totalTokens); - -const all = measureAskToolFootprint({ features: ALL_ASK_FEATURES }); +row("total", all.totalChars, all.totalTokens); const noExpiry = measureAskToolFootprint({ features: { ...ALL_ASK_FEATURES, expiry: false }, }); diff --git a/pi-ask/src/features.ts b/pi-ask/src/features.ts index c0b5db57..9d3acf42 100644 --- a/pi-ask/src/features.ts +++ b/pi-ask/src/features.ts @@ -2,9 +2,8 @@ import type { AskConfig } from "./config/schema.ts"; import type { AskSchemaFeatures } from "./schema.ts"; /** - * Optional model-facing surface of `ask_user`. A feature is registered only - * when its behaviour has shipped AND the user's config leaves it enabled; - * otherwise its fields are absent from the schema and cost nothing. + * Optional model-facing surface of `ask_user`. Disabled features are absent + * from the registered schema, so they cost no recurring context. */ export type AskFeatures = AskSchemaFeatures; @@ -18,22 +17,12 @@ export const ALL_ASK_FEATURES: AskFeatures = { expiry: true, }; -/** - * Features whose behaviour is implemented. Flip a flag to `true` in the same - * change that makes the tool honour the field; config can only narrow this. - */ -export const SHIPPED_ASK_FEATURES: AskFeatures = { - background: true, - expiry: true, -}; - /** Read once at registration, so a config change applies on reload only. */ export function resolveAskFeatures( - config: Pick, - shipped: AskFeatures = SHIPPED_ASK_FEATURES + config: Pick ): AskFeatures { return { - background: shipped.background && config.behaviour.background, - expiry: shipped.expiry && config.expiry.enabled, + background: config.behaviour.background, + expiry: config.expiry.enabled, }; } diff --git a/pi-ask/tests/token-ceiling.test.ts b/pi-ask/tests/token-ceiling.test.ts index fd932da5..0e1f4afb 100644 --- a/pi-ask/tests/token-ceiling.test.ts +++ b/pi-ask/tests/token-ceiling.test.ts @@ -8,7 +8,6 @@ import { type AskFeatures, NO_ASK_FEATURES, resolveAskFeatures, - SHIPPED_ASK_FEATURES, } from "../src/features.ts"; /** Est. tokens, measured exactly as `npm run tokens` does. */ @@ -54,14 +53,6 @@ test("ask_user footprint stays under the lower ceiling with expiry disabled", () } }); -test("everything that ships fits the all-enabled ceiling", () => { - assert.deepEqual(SHIPPED_ASK_FEATURES, ALL_ASK_FEATURES); - const { totalTokens } = measureAskToolFootprint({ - features: SHIPPED_ASK_FEATURES, - }); - assert.ok(totalTokens <= CEILING_ALL_ENABLED); -}); - test("a disabled feature is absent from the registered schema", () => { assert.deepEqual(schemaKeys(NO_ASK_FEATURES), { call: ["title", "questions"], @@ -81,23 +72,16 @@ test("a disabled feature is absent from the registered schema", () => { assert.ok(!noExpiry.question.includes("fallback")); }); -test("config can only narrow the shipped features", () => { - assert.deepEqual( - resolveAskFeatures(DEFAULT_ASK_CONFIG, ALL_ASK_FEATURES), - ALL_ASK_FEATURES - ); - assert.deepEqual( - resolveAskFeatures( - { - behaviour: { ...DEFAULT_ASK_CONFIG.behaviour, background: false }, - expiry: { ...DEFAULT_ASK_CONFIG.expiry, enabled: false }, - }, - ALL_ASK_FEATURES - ), - NO_ASK_FEATURES - ); - assert.deepEqual( - resolveAskFeatures(DEFAULT_ASK_CONFIG, NO_ASK_FEATURES), - NO_ASK_FEATURES - ); +test("registration features follow config independently", () => { + for (const background of [false, true]) { + for (const expiry of [false, true]) { + assert.deepEqual( + resolveAskFeatures({ + behaviour: { ...DEFAULT_ASK_CONFIG.behaviour, background }, + expiry: { ...DEFAULT_ASK_CONFIG.expiry, enabled: expiry }, + }), + { background, expiry } + ); + } + } }); From 44b733a7cbf213405c65f7fdb768b95542bf7025 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:11:07 +0000 Subject: [PATCH 37/38] docs(ask): document durable acknowledgements and retained drafts --- pi-ask/CHANGELOG.md | 3 ++- pi-ask/README.md | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/pi-ask/CHANGELOG.md b/pi-ask/CHANGELOG.md index 98c58fbb..168e44c5 100644 --- a/pi-ask/CHANGELOG.md +++ b/pi-ask/CHANGELOG.md @@ -8,7 +8,8 @@ - **Answer later.** `Ctrl+L` on a blocking form returns `deferred` and moves the form, draft intact, to a panel above the input. `Alt+A` moves the keyboard between panel and input; `Esc` or `Ctrl+L` hides it; a line under the input counts waiting forms. `/ask-panel` reopens it. - **Expiry with fallback.** A call can set `timeoutSeconds` and each question an optional `fallback` option `value`. On by default with a 30-second floor. The countdown runs only while the form is on screen, after the notification fires; any key, hiding or deferring stops it for good. On lapse the form resolves `expired` with only declared fallbacks applied, and the result says a fallback is the agent's assumption, not approval. - **Late override.** An expired form stays reopenable for an hour through `/ask-panel`; submitting sends one correction that replaces the timed-out result. Dismissing it without a comment leaves the earlier result standing. -- **Session journal and recovery.** Forms, drafts (including text typed in an editor and not yet submitted), panel state, countdown stops and outcomes are saved in the session. An interrupted form reopens on startup, resume or fork with its draft. Delivery stays exactly-once across reload, resume, compaction and branch moves: the `pi-ask:answer` message on the active branch is the proof, and a wake whose run never started is retried. +- **Session journal and recovery.** Forms, drafts (including text typed in an editor and not yet submitted), panel state, countdown stops and outcomes are saved in the session. An interrupted form reopens on startup, resume or fork with its draft. Delivery stays exactly-once across reload, resume, compaction and branch moves: the `pi-ask:answer` message on the active branch is the proof. Failed sends and wakes whose runs never started are retried; multiple recovered answers remain eligible until delivered. +- **No false acknowledgements.** Journal failures report an error instead of returning a receipt or completed answer. Panel forms keep their answers for retry, and temporary hiding or blocking forms retain the live editor without losing pending typing. - **Cancel with a comment and skip.** `c` on the review tab attaches a short reason to a cancellation. `s` declines one question without cancelling the form; skipped is neither an answer nor approval. - **Configuration and keys.** New keys `behaviour.background`, `expiry.enabled` and `expiry.minSeconds`, plus keymaps `global.later`, `global.panelFocus`, `main.skip` and `main.cancelComment`. `/ask-settings` exposes the expiry toggles; schema changes apply on `/reload`. `/ask-panel` shows waiting and expired forms. - **Hosts without the custom TUI** keep the blocking card flow: `background` blocks there and there is no countdown. diff --git a/pi-ask/README.md b/pi-ask/README.md index 3ed7e504..e3d388b8 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -117,6 +117,8 @@ The later answer is a `pi-ask:answer` message that names the request and each qu Every form, draft and outcome is journalled in the session. A form left open when Pi quit comes back in the panel on startup, resume or fork with its draft, and its answer reaches the agent once: delivery is decided from what the active branch already holds. The journal follows the active branch. +A receipt or completed tool result requires a successful journal write. Storage failures are reported rather than acknowledged; a panel form whose answer could not be saved stays editable for retry. Hiding the panel or temporarily covering it with a blocking form preserves its live editor, including typing not yet flushed to the journal. + Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the current chat model unless `answer.extractionModels` is set. `PI_ASK_LOCALE=zh` localizes the dialog cards and result summaries (Simplified Chinese). | Key | Default | Effect | From 4aa96d99c5b514eaa0d96925554b91ed9aef79f4 Mon Sep 17 00:00:00 2001 From: GaganSD Date: Wed, 18 Nov 2026 01:38:40 +0000 Subject: [PATCH 38/38] refactor(ask): remove unused background extension points --- pi-ask/src/background.ts | 51 +++++++++--------------------------- pi-ask/src/journal/replay.ts | 2 -- pi-ask/src/state/expiry.ts | 3 --- pi-ask/src/ui/controller.ts | 5 ---- pi-ask/src/ui/panel.ts | 3 --- 5 files changed, 12 insertions(+), 52 deletions(-) diff --git a/pi-ask/src/background.ts b/pi-ask/src/background.ts index 92742107..20c0e913 100644 --- a/pi-ask/src/background.ts +++ b/pi-ask/src/background.ts @@ -25,10 +25,7 @@ import { renderAskAnswerMessage, } from "./delivery.ts"; import { askStrings } from "./i18n.ts"; -import { - ASK_ANSWER_MESSAGE_TYPE, - type AskFormSnapshot, -} from "./journal/entries.ts"; +import { ASK_ANSWER_MESSAGE_TYPE } from "./journal/entries.ts"; import { AskJournalWriteError, readAskJournal } from "./journal/journal.ts"; import { type AskJournalRecord, @@ -57,7 +54,7 @@ import { reducePanel, } from "./state/panel.ts"; import { toAskResult } from "./state/result.ts"; -import type { AskParams, AskResult, AskState } from "./types.ts"; +import type { AskResult, AskState } from "./types.ts"; import { type AskPanel, createAskPanel } from "./ui/panel.ts"; export const ASK_PENDING_WIDGET_KEY = "pi-ask:pending"; @@ -69,15 +66,6 @@ export const ASK_PENDING_WIDGET_KEY = "pi-ask:pending"; */ export const EXPIRED_OFFER_MS = 60 * 60 * 1000; -export interface AskBackgroundDeps { - /** Runs `task` after the current lifecycle dispatch has finished. */ - defer?: (task: () => void) => void; - /** Clock for the countdown of queued forms; tests inject their own. */ - newTimer?: (seconds: number) => ExpiryTimer; - /** Epoch milliseconds; used for the late-override offer window. */ - now?: () => number; -} - export interface AskBackground { /** The session started, or the tree moved: rebuild from the branch. */ attach(ctx: ExtensionContext): void; @@ -120,10 +108,9 @@ export interface AskBackground { export function registerAskBackground( pi: ExtensionAPI, - runtime: AskRuntime, - deps: AskBackgroundDeps = {} + runtime: AskRuntime ): AskBackground { - const background = createAskBackground(pi, runtime, deps); + const background = createAskBackground(pi, runtime); runtime.background = background; pi.on("session_start", (_event, ctx) => background.attach(ctx)); pi.on("session_tree", (_event, ctx) => background.attach(ctx)); @@ -154,13 +141,9 @@ export function registerAskBackground( export function createAskBackground( pi: Pick, - { clock, flushers, journal, live }: AskRuntime, - deps: AskBackgroundDeps = {} + { clock, flushers, journal, live }: AskRuntime ): AskBackground { - const defer = deps.defer ?? ((task) => setTimeout(task, 0)); - const now = deps.now ?? clock?.now ?? Date.now; - const newTimer = - deps.newTimer ?? ((seconds) => createExpiryTimer(seconds, clock)); + const now = clock?.now ?? Date.now; const delivery = createAskDelivery(pi); const recorders = new Map void>(); // Content key of the draft each loaded form last started from or wrote, @@ -321,7 +304,7 @@ export function createAskBackground( const formState = panel.state(requestId) ?? applyDraftSnapshot( - createInitialState(formToParams(record.form)), + createInitialState(record.form), record.draft ); try { @@ -397,7 +380,7 @@ export function createAskBackground( requestId, config, draft: record.draft, - params: formToParams(record.form), + params: record.form, expiry: timers.get(requestId), ...(expired ? { banner: askStrings().lateOverrideBanner } : {}), }; @@ -446,7 +429,7 @@ export function createAskBackground( const formState = panel.state(requestId) ?? applyDraftSnapshot( - createInitialState(formToParams(record.form)), + createInitialState(record.form), record.draft ); return toAskResult(formState).unanswered.length; @@ -555,7 +538,7 @@ export function createAskBackground( function poke(next: ExtensionContext) { // Starting a turn from inside a lifecycle dispatch is too early. - defer(() => { + setTimeout(() => { if (disposed) { return; } @@ -564,7 +547,7 @@ export function createAskBackground( } catch { // A stale context: the next event tries again. } - }); + }, 0); } function adopt(next: ExtensionContext): boolean { @@ -598,7 +581,7 @@ export function createAskBackground( return 0; } if (origin === "background" && options.timeoutSeconds !== undefined) { - const timer = newTimer(options.timeoutSeconds); + const timer = createExpiryTimer(options.timeoutSeconds, clock); timer.subscribe({ stop: (reason) => journal.recordExpiryStop(requestId, reason), expire: () => expire(requestId), @@ -714,13 +697,3 @@ function editorIsEmpty(ctx: ExtensionContext): boolean { return false; } } - -export function formToParams(form: AskFormSnapshot): AskParams { - return { - title: form.title, - questions: form.questions, - ...(form.timeoutSeconds === undefined - ? {} - : { timeoutSeconds: form.timeoutSeconds }), - }; -} diff --git a/pi-ask/src/journal/replay.ts b/pi-ask/src/journal/replay.ts index 44161d9f..faf902b2 100644 --- a/pi-ask/src/journal/replay.ts +++ b/pi-ask/src/journal/replay.ts @@ -24,7 +24,6 @@ export interface BranchEntryLike { } export interface AskJournalRecord { - createdAt: number; /** A foreground form the user sent to the queue with "answer later". */ deferred: boolean; /** The user stopped this form's countdown; it never runs again. */ @@ -112,7 +111,6 @@ export function replayJournal( if (!records.has(journalEntry.requestId)) { records.set(journalEntry.requestId, { requestId: journalEntry.requestId, - createdAt: journalEntry.at, mode: journalEntry.mode === "background" ? "background" : "foreground", form: journalEntry.form, toolCallId: journalEntry.toolCallId, diff --git a/pi-ask/src/state/expiry.ts b/pi-ask/src/state/expiry.ts index 7f77ac92..f3243cc8 100644 --- a/pi-ask/src/state/expiry.ts +++ b/pi-ask/src/state/expiry.ts @@ -65,8 +65,6 @@ export interface ExpiryTimer { hide(): void; /** The user did something with the form. Stops the clock for good. */ interact(): void; - /** Total limit, after the floor. */ - readonly seconds: number; show(): void; /** Stop for good, with a reason (e.g. the user opened the panel). */ stop(reason: ExpiryStopReason): void; @@ -159,7 +157,6 @@ export function createExpiryTimer( } return { - seconds, view, subscribe(listener) { listeners.add(listener); diff --git a/pi-ask/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 8429bc66..83cbb16d 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -91,8 +91,6 @@ export interface AskFlowOptions { * owns the form's visibility does both. */ expiry?: { owned?: boolean; timer: ExpiryTimer }; - /** Called for every key the form receives, before it is handled. */ - onInput?: (data: string) => void; /** Called after every state change while the form is open. */ onStateChange?: (state: AskState) => void; /** @@ -143,7 +141,6 @@ interface AskFlowController { /** Set once the form has its result; nothing is journalled after that. */ finished: boolean; focused: boolean; - onInput?: (data: string) => void; onStateChange?: (state: AskState) => void; panel?: { onHide: () => void }; /** Trailing timer for draft reports made while the user types. */ @@ -218,7 +215,6 @@ export function createAskFlowController( expiry: params.expiry?.timer, finished: false, focused: false, - onInput: params.onInput, onStateChange: params.onStateChange, panel: params.panel, settingsOpen: false, @@ -282,7 +278,6 @@ export function createAskFlowController( try { // One key means the user is here: the countdown ends for good. controller.expiry?.interact(); - controller.onInput?.(data); handleControllerInput(controller, data); } catch (error) { reportJournalError(controller, error); diff --git a/pi-ask/src/ui/panel.ts b/pi-ask/src/ui/panel.ts index e209c946..daa3347f 100644 --- a/pi-ask/src/ui/panel.ts +++ b/pi-ask/src/ui/panel.ts @@ -49,8 +49,6 @@ export interface AskPanelCallbacks { onDone(requestId: string, result: AskResult): void; /** The user asked to put the panel away. */ onHide(requestId: string): void; - /** A key reached the form. */ - onInput?(requestId: string, data: string): void; onStateChange(requestId: string, state: AskState): void; } @@ -282,7 +280,6 @@ function createPanelForm( cwd: ctx.cwd, draft: form.draft, expiry: form.expiry && { timer: form.expiry }, - onInput: (data) => callbacks.onInput?.(requestId, data), onStateChange: (state) => callbacks.onStateChange(requestId, state), panel: { onHide: () => callbacks.onHide(requestId) }, rebuilt: form.rebuilt,