diff --git a/pi-ask/CHANGELOG.md b/pi-ask/CHANGELOG.md index 7b2a8605..168e44c5 100644 --- a/pi-ask/CHANGELOG.md +++ b/pi-ask/CHANGELOG.md @@ -1,5 +1,20 @@ # 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 (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. +- 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 - Add RPC dialog interviews with single/multi-select, free-text answers, back navigation, and review before submission. diff --git a/pi-ask/README.md b/pi-ask/README.md index 3ebb6407..e3d388b8 100644 --- a/pi-ask/README.md +++ b/pi-ask/README.md @@ -32,6 +32,51 @@ 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 | +| 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 + +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. + +### 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. + +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 @@ -39,36 +84,65 @@ 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 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. 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 -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 +- `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. + +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. + +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 | +| --- | --- | --- | +| `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: 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 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 | 528 | 132 | -| **total** | **1,502** | **376** | +| 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. + +A test holds the total to 450 with every optional field registered and 420 with expiry disabled. 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..34c45864 100644 --- a/pi-ask/scripts/token-report.mjs +++ b/pi-ask/scripts/token-report.mjs @@ -1,34 +1,23 @@ /** - * 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 } 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 all = measureAskToolFootprint({ features: ALL_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 all.parts) { + row(part.name, part.chars, part.tokens); } -console.log(` ${"total".padEnd(16)} ${String(totalChars).padStart(5)} / ${totalTokens}`); +row("total", all.totalChars, all.totalTokens); +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/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. diff --git a/pi-ask/src/ask-tool-helpers.ts b/pi-ask/src/ask-tool-helpers.ts index d32364aa..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, }; } @@ -105,11 +104,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/ask-tool.ts b/pi-ask/src/ask-tool.ts index 445a921a..90e250c6 100644 --- a/pi-ask/src/ask-tool.ts +++ b/pi-ask/src/ask-tool.ts @@ -12,13 +12,31 @@ import { successfulResponse, validateParams, } from "./ask-tool-helpers.ts"; -import { AskParamsSchema, stripSchemaDescriptions } from "./schema.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 type { AskParams } from "./types.ts"; +import { toAskResult } from "./state/result.ts"; +import type { AskParams, AskResult, AskState } 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; + /** Journal, live-form registry and queue; shared with the lifecycle. */ + 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", @@ -27,16 +45,26 @@ 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), + execute: (toolCallId, params, signal, _onUpdate, ctx) => + executeAskTool( + runtime, + features, + toolCallId, + params as AskParams, + ctx, + signal + ), renderCall: renderAskToolCall, renderResult: renderAskToolResult, }); } async function executeAskTool( + { background, clock, flushers, journal, live }: AskRuntime, + features: AskFeatures, + toolCallId: string, params: AskParams, ctx: ExtensionContext, signal?: AbortSignal @@ -45,20 +73,115 @@ async function executeAskTool( if (!validation.ok) { return invalidPayloadResponse(params, validation.issues); } + // 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 }); + const settle = (result: AskResult) => + journal.recordOutcome(requestId, result, "tool").result; 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")) + ); } + + // 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", { + timeoutSeconds: expirySeconds, + }); + 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 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), + registerFlush: (flush) => { + flushers.add(flush); + return () => flushers.delete(flush); + }, + }); + let result: AskResult; ctx.ui.setWorkingVisible(false); + live.add(requestId); try { - const result = await runAskFlow(ctx, params); - return successfulResponse(result); + // A blocking form owns the keyboard: the panel steps aside for it. + result = await (background + ? background.foreground(ctx, openForm) + : openForm()); } finally { + timer?.dispose(); + 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)); + } + 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. */ +function receipt( + state: AskState, + status: "queued" | "deferred", + requestId: string +): 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 new file mode 100644 index 00000000..20c0e913 --- /dev/null +++ b/pi-ask/src/background.ts @@ -0,0 +1,699 @@ +/** + * 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 { + BoundaryResult, + 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, + createAskDelivery, + renderAskAnswerMessage, +} from "./delivery.ts"; +import { askStrings } from "./i18n.ts"; +import { ASK_ANSWER_MESSAGE_TYPE } from "./journal/entries.ts"; +import { AskJournalWriteError, readAskJournal } from "./journal/journal.ts"; +import { + type AskJournalRecord, + getRecord, + isOpen, + pendingForms, + reopenableForms, +} from "./journal/replay.ts"; +import type { AskRuntime } from "./runtime.ts"; +import { createInitialState } from "./state/create.ts"; +import { + applyDraftSnapshot, + draftContentKey, + toDraftSnapshot, +} from "./state/draft.ts"; +import { + createExpiryTimer, + type ExpiryTimer, + toExpiredResult, +} from "./state/expiry.ts"; +import { + type AskPanelEvent, + EMPTY_PANEL, + panelTakesFocusKey, + panelView, + reducePanel, +} from "./state/panel.ts"; +import { toAskResult } from "./state/result.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"; + +/** + * 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 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 + ): BoundaryResult | 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", + 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. */ + 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(): void; +} + +export function registerAskBackground( + pi: ExtensionAPI, + runtime: AskRuntime +): AskBackground { + 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)); + pi.on("session_shutdown", () => background.dispose()); + pi.on("agent_start", () => background.started()); + pi.on("turn_end", (event, ctx) => background.boundary(ctx, event)); + pi.on( + "agent_before_settle", + (event, ctx) => background.boundary(ctx, event) + ); + 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 + ); + 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, + { clock, flushers, journal, live }: AskRuntime +): AskBackground { + 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, + // 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. + 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; + 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); + shown.set(requestId, draftContentKey(toDraftSnapshot(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, 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, + }; + } + + /** + * 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); + } + + /** A form counts down only while it is the one on screen. */ + function syncTimers() { + const view = panelView(state); + for (const [requestId, timer] of timers) { + // 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(); + } + } + } + + /** 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(record.form), + record.draft + ); + try { + complete(requestId, toExpiredResult(formState)); + } catch (error) { + if (!(error instanceof AskJournalWriteError)) { + throw error; + } + ctx?.ui.notify(error.message, "error"); + } + } + + 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); + syncTimers(); + 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"); + } + 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, + params: record.form, + expiry: timers.get(requestId), + ...(expired ? { banner: askStrings().lateOverrideBanner } : {}), + }; + } + + function updateIndicator() { + if (disposed || !ctx) { + return; + } + const forms = state.queue.length; + const lines = [ + 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, + }), + 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 + : lines.map((line) => ctx?.ui.theme.fg("dim", line) ?? line), + { placement: "belowEditor" } + ); + } + + function unansweredCount(requestId: string): number { + const record = records.get(requestId); + if (!record) { + return 0; + } + const formState = + panel.state(requestId) ?? + applyDraftSnapshot( + createInitialState(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); + // 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) || correcting) && + isQueued(requestId) && + result.status !== "unavailable" + ) { + 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 (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); + reopened.delete(requestId); + 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 }; + }); + } + + /** 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]); + } + 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. + setTimeout(() => { + if (disposed) { + return; + } + try { + delivery.pump(next); + } catch { + // A stale context: the next event tries again. + } + }, 0); + } + + 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; + } + reconcileBranch(next); + refresh((queue, hidden) => ({ type: "sync", queue, hidden })); + delivery.attach(next); + poke(next); + }, + poke, + 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 = createExpiryTimer(options.timeoutSeconds, clock); + 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" }); + } + 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; + } + // 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]); + } + 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. + } + }, + started() { + if (!disposed) { + delivery.started(); + } + }, + dispose() { + 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); + } catch { + // The UI is already gone. + } + disposed = true; + for (const [requestId, timer] of [...timers]) { + releaseTimer(requestId, timer); + } + 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; + } +} 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..54e5a949 100644 --- a/pi-ask/src/config/schema.ts +++ b/pi-ask/src/config/schema.ts @@ -24,10 +24,13 @@ 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({ cancel: Type.Optional(AskKeyBindingSchema), + cancelComment: Type.Optional(AskKeyBindingSchema), changeQuestionType: Type.Optional(AskKeyBindingSchema), confirm: Type.Optional(AskKeyBindingSchema), nextOption: Type.Optional(AskKeyBindingSchema), @@ -36,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({ @@ -76,11 +80,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({ @@ -107,10 +118,16 @@ 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: { cancel: string[]; + /** Review tab: cancel the form and say why. */ + cancelComment: string[]; changeQuestionType: string[]; confirm: string[]; nextOption: string[]; @@ -119,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: { @@ -145,10 +164,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/src/constants/keymaps.ts b/pi-ask/src/constants/keymaps.ts index f3b7fe47..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" @@ -90,6 +91,8 @@ export const DEFAULT_ASK_KEYMAPS: AskConfigKeymaps = { global: { dismiss: ["ctrl+c"], settings: ["?"], + later: ["ctrl+l"], + panelFocus: ["alt+a"], }, main: { confirm: ["enter"], @@ -102,6 +105,8 @@ export const DEFAULT_ASK_KEYMAPS: AskConfigKeymaps = { previousOption: ["up"], optionNote: ["n"], questionNote: ["shift+n"], + skip: ["s"], + cancelComment: ["c"], }, editor: { submit: ["enter"], @@ -131,6 +136,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", @@ -143,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", @@ -168,11 +177,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 +299,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"); @@ -304,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"), @@ -312,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, @@ -329,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, @@ -338,7 +364,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 +412,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 +422,8 @@ export function normalizeConfiguredKeymaps( } const contextResult = normalizeContextKeymaps( context, - rawContext as Record + rawContext as Record, + taken ); if (!contextResult.ok) { return contextResult; @@ -385,7 +441,8 @@ export function normalizeConfiguredKeymaps( function normalizeContextKeymaps( context: AskKeymapContext, - rawContext: Record + rawContext: Record, + taken: ReadonlySet ): | { ok: true; keymaps: Record } | { ok: false; error: string } { @@ -397,7 +454,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 +477,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 +501,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/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 new file mode 100644 index 00000000..6d76faa6 --- /dev/null +++ b/pi-ask/src/delivery.ts @@ -0,0 +1,312 @@ +/** + * 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 + * 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 { + BoundaryResult, + BoundaryState, + CustomMessageEntryDraft, + ExtensionAPI, + ExtensionContext, + MessageRenderer, +} 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 { readAskJournal } from "./journal/journal.ts"; +import { undeliveredOutcomes } from "./journal/replay.ts"; +import { renderResultText } from "./result.ts"; +import { + type AskDeliverySituation, + type AskDeliveryStep, + 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 type AskBoundaryEvent = Pick; + +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 + ): BoundaryResult | 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(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(): 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, + options: { correction?: boolean } = {} +): string { + const requestId = result.requestId ?? ""; + const strings = askStrings(); + const cancelled = result.status === "cancelled"; + 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 ?? []); + 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) => { + const asked = `- ${question.id} "${oneLine(question.prompt)}"`; + 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: string[] = expired + ? [ + strings.expiredSummary( + result.questions + .filter((question) => fallbacks.has(question.id)) + .map((question) => question.label) + ), + ] + : []; + 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 { + 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 parts.join("; ") || "(no answer)"; +} + +function oneLine(text: string): string { + return text.replace(/\s+/g, " ").trim(); +} + +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, { correction }), + display: true, + details, + }; +} + +export function createAskDelivery( + pi: Pick +): AskDelivery { + // 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; + // 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: true, + }).filter( + ({ outcome }) => outcome.channel === "message" || adopted.has(outcome.outcomeId) + ); + 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; + }, + attach(ctx) { + adopted = new Set( + undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true }) + .filter(({ outcome }) => outcome.channel === "tool") + .map(({ outcome }) => outcome.outcomeId) + ); + watching = true; + }, + 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()) { + // 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", + 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): CustomMessageEntryDraft => ({ + type: "custom_message", + ...answerMessage(outcome), + })), + ]; + const wantsTurn = + event.outcome === "completed" && + proposed.some((outcome) => outcome.result.status !== "cancelled"); + return wantsTurn ? { entries, continue: true } : { entries }; + }, + }; +} + +/** Transcript card for a delivered answer, in place of the raw message. */ +export const renderAskAnswerMessage: MessageRenderer = ( + message, + _options, + theme +) => { + const details = message.details; + const result = details?.result; + if (!(result && Array.isArray(result.questions))) { + return; + } + const strings = askStrings(); + 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 ")) + + 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 + ); +}; diff --git a/pi-ask/src/features.ts b/pi-ask/src/features.ts new file mode 100644 index 00000000..9d3acf42 --- /dev/null +++ b/pi-ask/src/features.ts @@ -0,0 +1,28 @@ +import type { AskConfig } from "./config/schema.ts"; +import type { AskSchemaFeatures } from "./schema.ts"; + +/** + * 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; + +export const NO_ASK_FEATURES: AskFeatures = { + background: false, + expiry: false, +}; + +export const ALL_ASK_FEATURES: AskFeatures = { + background: true, + expiry: true, +}; + +/** Read once at registration, so a config change applies on reload only. */ +export function resolveAskFeatures( + config: Pick +): AskFeatures { + return { + background: config.behaviour.background, + expiry: config.expiry.enabled, + }; +} diff --git a/pi-ask/src/i18n.ts b/pi-ask/src/i18n.ts index e2795a0e..1e23c893 100644 --- a/pi-ask/src/i18n.ts +++ b/pi-ask/src/i18n.ts @@ -29,6 +29,85 @@ 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". */ + 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. */ + 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; + /** 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. */ + 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; + correctedCardLabel: string; + expiredCardLabel: 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 = + "这只是回执,不是回答,也不是批准。只继续不依赖该回答的工作;回答会在之后的消息中送达。不要重复提问。"; + +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; } const EN_STRINGS: AskStrings = { @@ -44,6 +123,70 @@ 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)` : "" + }. ${EN_RECEIPT_RULES}`, + deferredSummary: (requestId) => + `User will answer later (${requestId}). ${EN_RECEIPT_RULES}`, + fallbackMark: "[fallback: not chosen by the user]", + expiredSummary: (fallbackLabels) => + [ + "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 and risky 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.`, + 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.`, + 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 }) => + [ + 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", + correctedCardLabel: "corrected", + expiredCardLabel: "timed out", + queuedLabel: "Queued", + deferredLabel: "Answer later", + expiredLabel: "Expired", }; const ZH_STRINGS: AskStrings = { @@ -59,6 +202,68 @@ 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} 个表单待回答)` : "" + }。${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)}:`, + 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)} 超时后取消了它。你应用过的备选项一律撤回。取消不代表批准;有风险的操作仍须保持阻止。`, + countdownRunning: (remaining, hasFallback) => + hasFallback + ? `⏱ ${remaining} 内无回复:将应用标记的备选项。按任意键停止倒计时。` + : `⏱ ${remaining} 后超时,不会应用任何答案。按任意键停止倒计时。`, + countdownStopped: "倒计时已停止;此表单现在等你回答。", + fallbackOptionMarker: "(备选项)", + lateOverrideBanner: "此表单已超时。你的回答会作为更正发送给代理。", + expiredIndicator: (count) => + `↺ ${count} 个已超时的表单仍可回答 · /ask-panel`, + 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: "已取消", + correctedCardLabel: "已更正", + expiredCardLabel: "已超时", + queuedLabel: "已排队", + deferredLabel: "稍后回答", + expiredLabel: "已超时", }; /** Strings for PI_ASK_LOCALE; any zh* tag picks Simplified Chinese. */ diff --git a/pi-ask/src/index.ts b/pi-ask/src/index.ts index f295fd5c..c8bd964a 100644 --- a/pi-ask/src/index.ts +++ b/pi-ask/src/index.ts @@ -2,11 +2,19 @@ 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 { registerAskBackground } from "./background.ts"; +import { getAskConfigStore, resetAskConfigStore } from "./config/store.ts"; +import { resolveAskFeatures } from "./features.ts"; +import { createAskRuntime } from "./runtime.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()); + const runtime = createAskRuntime(pi); + registerAskBackground(pi, runtime); + registerAskTool(pi, { features, runtime }); registerAskSettingsCommand(pi); registerAnswerCommands(pi); } diff --git a/pi-ask/src/journal/entries.ts b/pi-ask/src/journal/entries.ts new file mode 100644 index 00000000..b6466180 --- /dev/null +++ b/pi-ask/src/journal/entries.ts @@ -0,0 +1,191 @@ +/** + * 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, 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. + */ +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 is + * sent as a follow-up; the `pi-ask:answer` message on the branch proves it. + */ +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; + /** Question ids the user skipped. */ + skipped?: string[]; + /** 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; + /** The expired outcome this one corrects (late override). */ + supersedes?: 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"; +} + +/** 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 + | 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; +} + +const ENTRY_KINDS = new Set([ + "form", + "draft", + "defer", + "outcome", + "panel", + "expiry", + "dismiss", +]); + +/** 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 "panel": + 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; + } +} + +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..cf4bd372 --- /dev/null +++ b/pi-ask/src/journal/journal.ts @@ -0,0 +1,179 @@ +/** + * 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 AskExpiryStopReason, + 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; + /** 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. */ + 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, + supersedes?: string + ): 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; + } + write({ kind: "draft", requestId, draft }); + lastKey = key; + }; + }, + recordDefer(requestId) { + write({ kind: "defer", requestId }); + }, + recordPanel(hidden, requestId = "") { + write({ kind: "panel", requestId, hidden }); + }, + 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 }); + }, + }; +} + +/** 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 (error) { + throw new AskJournalWriteError(entry, error); + } + }, 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..faf902b2 --- /dev/null +++ b/pi-ask/src/journal/replay.ts @@ -0,0 +1,278 @@ +/** + * 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 { + /** 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; + /** + * 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; + /** + * 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; +} + +export interface AskJournalState { + /** The user put the background panel away on this branch. */ + panelHidden: boolean; + /** 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(); + 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") { + 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 === "panel") { + panelHidden = journalEntry.hidden; + continue; + } + if (journalEntry.kind === "form") { + if (!records.has(journalEntry.requestId)) { + records.set(journalEntry.requestId, { + requestId: journalEntry.requestId, + 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, + 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; + // 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; + default: + break; + } + } + + for (const [outcomeId, requestId] of deliveredOutcomeIds) { + records.get(requestId)?.delivered.add(outcomeId); + } + return { panelHidden, 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) + ); +} + +/** + * 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(), + 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. 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.offerDismissed && + (!offer || offer.now - record.outcome.at <= offer.maxAgeMs) + ); +} + +/** Records whose latest outcome still has to be sent as a follow-up. */ +export function undeliveredOutcomes( + state: AskJournalState, + options: { unrecordedTool?: boolean } = {} +): Array { + return state.records.filter( + (record): record is AskJournalRecord & { outcome: AskOutcomeEntry } => + !!record.outcome && + !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)) + ); +} + +/** 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/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/result-format.ts b/pi-ask/src/result-format.ts index 4e5b9547..480f1f28 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,9 +9,15 @@ export function formatResultLines( const lines: string[] = []; 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; @@ -18,7 +25,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 +53,21 @@ 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 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 89e83a0c..f77d198d 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"; @@ -10,12 +11,24 @@ 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"; } + 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/runtime.ts b/pi-ask/src/runtime.ts new file mode 100644 index 00000000..879bb8b0 --- /dev/null +++ b/pi-ask/src/runtime.ts @@ -0,0 +1,39 @@ +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. + */ + 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 + * skips them: an open form is not an interrupted one. + */ + live: Set; +} + +export function createAskRuntime( + pi: Pick, + clock?: ExpiryClock +): AskRuntime { + return { + clock, + flushers: new Set(), + journal: createSessionAskJournal(pi, clock && { now: clock.now }), + live: new Set(), + }; +} 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/src/state/draft.ts b/pi-ask/src/state/draft.ts new file mode 100644 index 00000000..d0e12e51 --- /dev/null +++ b/pi-ask/src/state/draft.ts @@ -0,0 +1,64 @@ +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), + ...(state.skipped?.length ? { skipped: [...state.skipped] } : {}), + 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; + 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(), + }; +} + +/** 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, + 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/expiry.ts b/pi-ask/src/state/expiry.ts new file mode 100644 index 00000000..f3243cc8 --- /dev/null +++ b/pi-ask/src/state/expiry.ts @@ -0,0 +1,253 @@ +/** + * 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; + 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 { + 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/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/outbox.ts b/pi-ask/src/state/outbox.ts new file mode 100644 index 00000000..c0257543 --- /dev/null +++ b/pi-ask/src/state/outbox.ts @@ -0,0 +1,76 @@ +/** + * 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"); + }); +} 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/src/state/result.ts b/pi-ask/src/state/result.ts index a76b3c21..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"; @@ -65,11 +82,40 @@ 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 ?? "", result.pending); + } + if (result.status === "deferred") { + return askStrings().deferredSummary(result.requestId ?? ""); + } 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"); + } 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 + .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/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 0acd9fb3..e9397354 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,33 @@ 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; + /** 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[]; + /** 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[]; @@ -88,16 +111,22 @@ 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; 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/src/ui/controller.ts b/pi-ask/src/ui/controller.ts index 37775a00..83cbb16d 100644 --- a/pi-ask/src/ui/controller.ts +++ b/pi-ask/src/ui/controller.ts @@ -4,9 +4,15 @@ 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"; +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"; import { getEditorDraft, saveEditorDraft, @@ -29,8 +35,10 @@ import { import { applyNumberShortcut, confirmCurrentSelection, + enterCancelComment, enterOptionNoteMode, enterQuestionNoteMode, + skipCurrentQuestion, toggleCurrentMultiOption, } from "../state/transitions.ts"; import { isEditingView } from "../state/view.ts"; @@ -59,18 +67,84 @@ 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 { + /** + * 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; + /** 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 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 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; + /** + * 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`. */ +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; + /** The live form state, including unsaved editor text. */ + getState(): AskState; + handleInput(data: string): void; + invalidate(): void; + render(width: number): string[]; +} + interface AskFlowController { + allowDefer: boolean; + banner?: string; config: AskConfig; configNotice?: string; ctx: ExtensionContext; done: Done; editor: Editor; + expiry?: ExpiryTimer; + /** Set once the form has its result; nothing is journalled after that. */ + finished: boolean; + focused: boolean; + 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; @@ -83,9 +157,13 @@ 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 + params: AskParams, + options: AskFlowOptions = {} ): Promise { const store = getAskConfigStore(); const { config, notice } = await store.ensureLoaded(); @@ -95,6 +173,7 @@ export async function runAskFlow( return ctx.ui.custom((...args) => createAskFlowController(args, { ...params, + ...options, config, configNotice: notice?.text, cwd: ctx.cwd, @@ -103,23 +182,43 @@ export async function runAskFlow( ); } -function createAskFlowController( +export function createAskFlowController( [tui, theme, _keybindings, done]: [ Tui, Theme, - Keybindings, + Keybindings | undefined, (result: AskResult) => void, ], params: AskFlowParams -) { +): AskFlowComponent { + let unregisterFlush = () => { + // replaced once the controller exists + }; const controller: AskFlowController = { + allowDefer: params.allowDefer === true, + banner: params.banner, config: params.config, configNotice: params.configNotice, ctx: params.ctx, - done, + done: (result) => { + controller.finished = true; + try { + done(result); + } catch (error) { + controller.finished = false; + reportJournalError(controller, error); + return; + } + unregisterFlush(); + }, editor: createEditor(tui, theme, params.cwd), + expiry: params.expiry?.timer, + finished: false, + focused: false, + onStateChange: params.onStateChange, + panel: params.panel, settingsOpen: false, - state: createInitialState(params), + state: applyDraftSnapshot(createInitialState(params), params.draft), suppressAutoInputForSelection: false, pendingDiscardConfirm: false, pendingQuestionTypeChangeQuestionId: undefined, @@ -143,42 +242,151 @@ function createAskFlowController( maybeFinish(controller); }); + unregisterFlush = + params.registerFlush?.(() => flushDraft(controller)) ?? unregisterFlush; 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); + 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() { - return controller.editor.focused; + return controller.focused; }, set focused(value: boolean) { + controller.focused = value; controller.editor.focused = value; }, + getState: () => snapshotState(controller), render: (width: number) => renderController(controller, width), invalidate() { controller.editor.invalidate(); }, handleInput(data: string) { - handleControllerInput(controller, data); + try { + // One key means the user is here: the countdown ends for good. + controller.expiry?.interact(); + handleControllerInput(controller, data); + } catch (error) { + reportJournalError(controller, error); + } + }, + detach() { + cancelDraftTimer(controller); + controller.onStateChange = undefined; + this.dispose(); }, dispose() { + flushDraft(controller); + unregisterFlush(); + 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) { + 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) { + 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; + 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), reviewShortcutHint: getActiveReviewShortcutHint(controller), state: controller.state, + surface: controller.panel + ? { panel: { focused: controller.focused } } + : { defer: controller.allowDefer }, theme: controller.theme, width, }); @@ -203,7 +411,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; @@ -218,6 +429,10 @@ function handleEditingCommand( handleExitFlow(controller, dismissFlow(controller.state)); return; } + if (command.kind === "later") { + answerLater(controller); + return; + } if (command.kind === "showSettings") { showSettingsModal(controller); return; @@ -240,7 +455,7 @@ function handleEditingCommand( } if (command.kind === "delegateToEditor") { controller.editor.handleInput(data); - refresh(controller); + refresh(controller, { typing: true }); } } @@ -265,6 +480,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); @@ -282,8 +507,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; @@ -413,6 +647,28 @@ 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 = snapshotState(controller); + controller.pendingDiscardConfirm = false; + cancelDraftTimer(controller); + 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 }); @@ -527,18 +783,28 @@ function showSettingsModal(controller: AskFlowController) { }); } -function refresh(controller: AskFlowController) { +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(); } 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/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 a87deba3..6f2f0637 100644 --- a/pi-ask/src/ui/input.ts +++ b/pi-ask/src/ui/input.ts @@ -19,7 +19,10 @@ export type AskInputCommand = | { kind: "confirm" } | { kind: "cancel" } | { kind: "changeQuestionType" } + | { kind: "skipQuestion" } + | { kind: "cancelWithComment" } | { kind: "dismiss" } + | { kind: "later" } | { kind: "showSettings" } | { kind: "numberShortcut"; digit: number } | { kind: "editMoveTab"; delta: 1 | -1 } @@ -39,6 +42,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" }; } @@ -46,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); } @@ -155,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/panel.ts b/pi-ask/src/ui/panel.ts new file mode 100644 index 00000000..daa3347f --- /dev/null +++ b/pi-ask/src/ui/panel.ts @@ -0,0 +1,288 @@ +/** + * 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 { 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"; + +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 { + banner?: string; + config: AskConfig; + draft?: AskDraftSnapshot; + /** 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; +} + +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; + 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 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. */ + state(requestId: string): AskState | undefined; +} + +export function createAskPanel(callbacks: AskPanelCallbacks): AskPanel { + 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 + // 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, + requestId: string, + load: (requestId: string) => AskPanelForm | undefined + ) { + const build = (tui: Tui, theme: Theme) => { + mounted = { tui, ui: ctx.ui }; + if (form?.requestId !== requestId || form.ui !== ctx.ui) { + unloadForm(); + const next = load(requestId); + if (next) { + form = { + requestId, + ui: ctx.ui, + 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(); + ctx.ui.setWidget(ASK_PANEL_WIDGET_KEY, build, { + 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 + ) { + mount(ctx, view.formId, load); + } + if (!form) { + unmount(); + return true; + } + if (!view.focused) { + releaseFocus(); + mounted?.tui.requestRender(); + return true; + } + const taken = takeFocus(); + mounted?.tui.requestRender(); + return taken; + }, + discard() { + 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(); + } + }, + 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, + banner: form.banner, + config: form.config, + ctx, + cwd: ctx.cwd, + draft: form.draft, + expiry: form.expiry && { timer: form.expiry }, + onStateChange: (state) => callbacks.onStateChange(requestId, state), + panel: { onHide: () => callbacks.onHide(requestId) }, + rebuilt: form.rebuilt, + } + ); +} diff --git a/pi-ask/src/ui/render-frame.ts b/pi-ask/src/ui/render-frame.ts index 8ce5f02d..075c25ff 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, @@ -13,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)))); @@ -26,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: { @@ -33,12 +44,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(); @@ -60,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, @@ -188,26 +204,28 @@ 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 === "comment") { + context = "comment"; } 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-question.ts b/pi-ask/src/ui/render-question.ts index 2ef57fbc..405a4aa6 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, @@ -21,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) { @@ -166,7 +178,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-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-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 802a03c8..be9d32cf 100644 --- a/pi-ask/src/ui/render.ts +++ b/pi-ask/src/ui/render.ts @@ -1,4 +1,11 @@ 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, getRenderableOptions, @@ -11,19 +18,27 @@ 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; + surface?: FooterSurface; theme: Theme; width: number; editor: QuestionRenderContext["editor"]; }): string[] { const { + banner, config, + countdown, footerNotice, reviewShortcutHint, state, + surface, theme, width, editor, @@ -32,10 +47,16 @@ 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); + renderSubmitScreen(lines, state, theme, width, reviewShortcutHint, editor); } else if (question) { renderQuestionScreen({ lines, @@ -45,9 +66,38 @@ export function renderAskScreen(args: { theme, width, editor, + fallbackMarked: countdown?.phase === "running", }); } - renderFrameFooter({ config, footerNotice, lines, state, theme, width }); + renderFrameFooter({ + config, + footerNotice, + lines, + state, + surface, + theme, + width, + }); 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 d5d5d090..371f0edd 100644 --- a/pi-ask/src/ui/settings-list.ts +++ b/pi-ask/src/ui/settings-list.ts @@ -34,8 +34,11 @@ const DESCRIPTION_LINE_COUNT = 3; const COMPACT_WIDTH = 40; const RESET_CONFIRMATION_MS = 2000; -type SettingSection = "Actions" | "Live settings"; -type ToggleSettingKey = keyof AskConfig["behaviour"] | "notifications.enabled"; +type SettingSection = "Actions" | "Live settings" | "After /reload"; +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 = [ { @@ -95,6 +104,30 @@ 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: + "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.", @@ -323,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); } @@ -335,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 { @@ -357,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(); } @@ -376,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/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/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/background-delivery.test.ts b/pi-ask/tests/background-delivery.test.ts new file mode 100644 index 00000000..83c9a2ff --- /dev/null +++ b/pi-ask/tests/background-delivery.test.ts @@ -0,0 +1,428 @@ +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 { + boot, + start, + kinds, + ONE, + SUBMIT_ONE, + SUBMIT_TWO, + withBackgroundForm, + unrecordedToolSession, +} from "./support/background.ts"; + +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; + 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); + 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(host.answers()[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(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. + 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], outcome: "completed" }) 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("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(); + 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/); +}); + +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..f4610f3e --- /dev/null +++ b/pi-ask/tests/background-panel.test.ts @@ -0,0 +1,230 @@ +import assert from "node:assert/strict"; +import test, { beforeEach, mock } 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 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); + 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 new file mode 100644 index 00000000..7d9ee0b8 --- /dev/null +++ b/pi-ask/tests/background.test.ts @@ -0,0 +1,158 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +import { registerAskTool } from "../src/ask-tool.ts"; +import { fakePi, KEY, quietConfig, tick } from "./support/fake-pi.ts"; +import { + boot, + start, + kinds, + PARAMS, + ONE, + SUBMIT_TWO, + withBackgroundForm, +} from "./support/background.ts"; + +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"]); +}); + +// --- 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"); +}); 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/contract.test.ts b/pi-ask/tests/contract.test.ts index c56d5f25..2b33a676 100644 --- a/pi-ask/tests/contract.test.ts +++ b/pi-ask/tests/contract.test.ts @@ -12,16 +12,17 @@ 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[] = []; registerAskTool({ + appendEntry() {}, registerTool(tool: unknown) { tools.push(tool as Record); }, @@ -225,3 +226,104 @@ 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("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)")); + assert.ok(none.includes("No fallback was applied.")); +}); 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/expiry-flow.test.ts b/pi-ask/tests/expiry-flow.test.ts new file mode 100644 index 00000000..30a0899b --- /dev/null +++ b/pi-ask/tests/expiry-flow.test.ts @@ -0,0 +1,527 @@ +import assert from "node:assert/strict"; +import test, { beforeEach } from "node:test"; +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"; +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, runtime, 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); + +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 () => { + 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 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 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 }); + 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 new file mode 100644 index 00000000..203d38d1 --- /dev/null +++ b/pi-ask/tests/expiry.test.ts @@ -0,0 +1,227 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createInitialState } from "../src/state/create.ts"; +import { + applyFallbacks, + createExpiryTimer, + effectiveTimeoutSeconds, + formatRemaining, + toExpiredResult, +} from "../src/state/expiry.ts"; +import type { AskParams } from "../src/types.ts"; +import { fakeClock } from "./support/fake-clock.ts"; + +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, {}); +}); 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/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/journal-replay.test.ts b/pi-ask/tests/journal-replay.test.ts new file mode 100644 index 00000000..bfa12a88 --- /dev/null +++ b/pi-ask/tests/journal-replay.test.ts @@ -0,0 +1,382 @@ +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, + pendingForms, + 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"); + 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 answer is on the branch", () => { + 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.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.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( + 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), []); +}); + +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); +}); + +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/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" + ); +}); diff --git a/pi-ask/tests/outbox.test.ts b/pi-ask/tests/outbox.test.ts new file mode 100644 index 00000000..e9be8ab8 --- /dev/null +++ b/pi-ask/tests/outbox.test.ts @@ -0,0 +1,147 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { formatDeliveredOutcome } from "../src/delivery.ts"; +import { + type AskDeliveryItem, + 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", + ]); +}); + +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" }, + ]); +}); + +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/); +}); + +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/); +}); 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 }); +}); 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/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/pi-ask/tests/settings-list.test.ts b/pi-ask/tests/settings-list.test.ts index 9136c1a1..d4f6453d 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"], @@ -241,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/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/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/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/support/fake-pi.ts b/pi-ask/tests/support/fake-pi.ts new file mode 100644 index 00000000..9cb848c5 --- /dev/null +++ b/pi-ask/tests/support/fake-pi.ts @@ -0,0 +1,389 @@ +/** + * A fake Pi host for lifecycle tests: a real in-memory SessionManager (so + * 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 { + 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"; +import type { AskResult } from "../../src/types.ts"; + +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 { + message: { + content: string; + customType: string; + details?: any; + display: boolean; + }; + 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, + 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; + /** Model a process that dies before Pi records a tool result. */ + persistToolResults?: boolean; + persistSentMessages?: boolean; + } = {} +) { + 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"][] = []; + 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. + let failWake = false; + let aborts = 0; + + const editor: FakeComponent & { text: string } = { + text: "", + focused: true, + handleInput(data) { + editor.text += data; + }, + }; + let focus: FakeComponent | null = editor; + const tui = { + terminal: { rows: 40, columns: 80 }, + 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"] | CustomMessageEntryDraft) { + 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) { + handlers.set(event, [...(handlers.get(event) ?? []), handler]); + return () => {}; + }, + 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); + }, + 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 (sendOptions?.triggerTurn) { + if (idle) { + if (failWake) { + failWake = false; + return; + } + 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, + 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, outcome: AgentActivityOutcome) { + let entries: SessionBoundaryDraft[] = []; + let proceed = false; + for (const handler of handlers.get(event) ?? []) { + 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; + } + 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, + session, + sent, + forms, + notices, + tools, + commands, + renderers, + widgets, + editor, + get aborts() { + return aborts; + }, + 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, + /** The run started by an idle wake writes its starting message. */ + recordWake() { + for (const message of wakes.splice(0)) { + persist(message); + } + }, + 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; + 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() + .filter( + (entry: any) => + entry.type === "custom" && + entry.customType === ASK_JOURNAL_ENTRY_TYPE + ) + .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"); + }, + }; +} + +/** 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/pi-ask/tests/token-ceiling.test.ts b/pi-ask/tests/token-ceiling.test.ts new file mode 100644 index 00000000..0e1f4afb --- /dev/null +++ b/pi-ask/tests/token-ceiling.test.ts @@ -0,0 +1,87 @@ +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, +} 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, + ]) { + 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("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 } + ); + } + } +}); diff --git a/scripts/packages.mjs b/scripts/packages.mjs index 91eb7a2f..55925944 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"], - commands: ["answer", "ask-settings"], tools: ["ask_user"], + 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"], }, "pi-automode": { name: "@gagansd/pi-automode", tests: "tests",