Skip to content

feat(ask): background questions, answer later and expiry - #132

Merged
GaganSD merged 38 commits into
mainfrom
feat/pi-ask-async
Nov 18, 2026
Merged

GaganSD merged 38 commits into
mainfrom
feat/pi-ask-async

Conversation

@GaganSD

@GaganSD GaganSD commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

ask_user in pi-ask gains asynchronous questions while keeping its small context footprint (400 est. tokens with everything enabled, ceiling 450). The agent can ask in the background and keep working, the user can defer a form and answer later, and a question can expire to a fallback the model declared up front. A session journal makes forms survive quits and delivers each answer exactly once.

What

  • Background questions — background: true returns a queued receipt; the form sits in a non-modal panel above the editor and the answer arrives at the next turn boundary or wakes an idle agent.
  • Answer later — Ctrl+L on any form returns deferred; the form moves to the panel with its draft.
  • Expiry — timeoutSeconds (call) and fallback (question). Visible countdown, 30s floor, any keypress stops the clock for good, only declared fallbacks apply, and the expired result states it is not approval. Expired forms can be reopened and corrected.
  • Safety and recovery — session journal, interrupted-form recovery, exactly-once delivery, branch scoping, pending indicator, cancel with a comment (c), skip one question (s).
  • Config — expiry.enabled, expiry.minSeconds, behaviour.background; disabled features are removed from the schema. Toggles in /ask-settings; /ask-panel and Alt+A focus the panel.

Why

Blocking forms stall long agent runs and lose state when Pi quits. This adds async without a second tool or recurring prompt cost: guidance lives in result text, and a test enforces the token ceiling.

Related issues

None.

Testing

  • npm run lint|typecheck|test:unit|test:integration|build --prefix pi-ask, npm run tokens --prefix pi-ask, npm run test:tooling — all pass.
  • Exercised in an isolated real Pi 1.5.2 with a scripted local model: background receipt and mid-run answer, idle wake, defer, countdown and expiry, stop-on-keypress, skip, cancel comment, recovery after restart.
  • Fakes only: late override, branch switch/fork, compaction, turn-boundary delivery of expired forms, RPC card flow ignoring timeoutSeconds.

Compatibility

Additive. Existing calls and result statuses are unchanged; three new statuses (queued, deferred, expired) appear only when the new fields or the defer key are used. Old configs gain the new keys with defaults. No version bump here; intended for 0.2.0.

Risk

Async delivery has a long bug tail, and a fallback could be misread as consent. Mitigated by result wording, stop-on-interaction, the 30s floor and the off switch. Field names (timeoutSeconds, fallback) are to be evaluated before publish.

Types and validation for background, timeoutSeconds and per-question
fallback, plus result text that carries the receipt and fallback rules.
Nothing is exposed in the registered schema yet.
expiry.enabled, expiry.minSeconds (30s floor) and behaviour.background
default on. Older configs keep loading; peek() reads config for
registration without creating the file.
buildAskParamsSchema registers background, timeoutSeconds and fallback
only for features that have shipped and that config leaves enabled.
The footprint measure is shared by npm run tokens and a ceiling test
(450 all enabled, 420 with expiry disabled).
Journal entry types for forms, drafts, defers, outcomes and delivery
markers, a writer, and a pure reducer that rebuilds form records from
the active branch: interrupted forms, the FIFO queue, reopenable
expired forms and undelivered outcomes.
Every valid ask_user call saves its form before waiting, its drafts as
answers change and its outcome before returning. In TUI mode a
foreground form left open when Pi stopped reopens with its draft on
session start or tree navigation; the answer goes to the agent as a
follow-up message exactly once, tracked per outcome on the active
branch.
Two global actions, configurable like the rest: `later` (Ctrl+L) and
`panelFocus` (Alt+A). The footer takes the surface a form is drawn on,
so a blocking form can offer "answer later" and the panel can show hide,
cancel-form and switch-to-input hints.

A config file written before an action existed now keeps its bindings:
the missing action takes its default, minus any key the user already
bound, instead of the whole keymap falling back to defaults. An empty
key list is an unbound action.
A `panel` journal entry records that the user hid or reopened the
background panel, so visibility follows the active branch like the forms
do. `pendingForms` is the single queue the panel shows: queued and
interrupted forms in request order, minus blocking forms that are on
screen in this process.
state/panel.ts decides which form the panel shows and who owns the
keyboard: one form at a time in request order, a blocking form takes
over and the panel returns as it was, a hidden panel never reopens or
takes focus, a rebuild never takes focus.

state/outbox.ts decides how an undelivered outcome is sent: proposed at
a turn boundary while the agent works, a wake when it is idle, appended
without a turn for cancellations and after an aborted run, and held
while already on its way.
Forms no tool call waits for share one queue, one panel and one way
back to the agent:

- The panel is a widget above Pi's editor. The editor keeps its text and
  stays usable; Alt+A moves the keyboard between the two, Esc or Ctrl+L
  hides the panel without cancelling, /ask-panel reopens it. A line
  under the editor counts unanswered questions, hidden ones included.
- One form at a time in request order across background, deferred and
  recovered forms. A blocking call takes the keyboard while it is open
  and the panel returns afterwards as it was. A new request takes focus
  only when the input is empty; a hidden panel never reopens by itself.
- Ctrl+L on a blocking form returns a `deferred` receipt and moves the
  form to the queue with its draft and its request-order place.
- `background: true` journals the form and returns a `queued` receipt
  with the request id and pending count. Hosts without the TUI still
  block (card flow) or report `unavailable`.
- Delivery is decided from the branch: an outcome is delivered when its
  pi-ask:answer message is there. A working agent gets it as a
  turn-boundary entry, an idle one is woken, a cancellation and anything
  left after an aborted run are appended without starting a turn. The
  message names the request and each question by id and prompt, and
  renders as a compact card.

Interrupted-form recovery now goes through the same panel instead of a
blocking form, so recovery.ts is gone. Queue, drafts and visibility are
rebuilt from the active branch on start, reload, resume, fork and tree
navigation; a form from another branch writes nothing.
`background` is now part of the registered schema when
`behaviour.background` is on (384 est. tokens, up from 376). With it
off the field is absent and a stale call that still carries it blocks.
/ask-settings gains a "Background questions" toggle under "After
/reload", since schema settings never change mid-session.
The countdown only starts when the form is armed and on screen, and can
only stop: interaction, hiding, or expiry end it for good. Time and timers
are injected. Fallbacks apply only to declared, unanswered questions.
Adds expiry and dismiss entries, a supersedes link on outcomes, an offer
window for reopening expired forms, and delivery text for timed-out forms
and late corrections.
timeoutSeconds and fallback ship in the schema when expiry is on. The clock
starts when a form is on screen and notified, stops for good on any key,
hide or takeover, and never runs for a form recovered after a restart. An
expired background form wakes an idle agent; an expired form can be
reopened for one late correction. /ask-settings toggles expiry and shows
the floor.
s skips the current question (answer and notes dropped, listed in
skipped, marked on the tab and the review). c on the review tab attaches a
comment to Cancel, carried in the cancelled result and the delivered
message. Neither key fires inside a text editor; both are keymap entries
with footer hints.
A tool-channel answer adopted on a rebuild stayed in flight when its wake
run failed to start, so it was held until the next reload or fork.

Count adopted tool outcomes when releasing sends the branch lacks, and
re-arm the adoption when such a send is dropped, so the next plan retries
it in the same process. Keep the adoption armed after a plan that could
only hold the outcome. Delivery stays exactly-once: the branch message or
tool result remains the only proof.
The 1,598 and 1,534 figures are characters; the token estimates are 400
and 384, which is what the 450/420 ceilings are denominated in.
@GaganSD
GaganSD marked this pull request as ready for review November 17, 2026 03:40
@GaganSD

GaganSD commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

@greptile-apps please review

@greptile-apps

greptile-apps Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The reviewed changes appear safe to merge; both previously reported problems are addressed.

Summary

This update preserves unfinished answers during shutdown and rebuilds open forms when the active branch has a different saved draft.

  • Background questions wait in a panel and deliver answers later.
  • Questions can time out to declared fallbacks and accept a later correction.
  • Users can skip one question or explain why they cancel a form.
  • Settings control which new question fields and shortcuts are available.

Both previous findings are addressed. No new actionable issues were found.

Reviews (2) · Last reviewed commit: "fix(ask): flush a blocking form's draft ..." · Reviewed by Greptile

Comment thread pi-ask/src/ui/controller.ts Resolved
Comment thread pi-ask/src/background.ts Resolved
The journal now records the form with the open editor's text folded in,
so a custom answer or note typed but not yet submitted survives a restart.
Keystrokes are reported after a short pause and flushed on any other
state change, answer later and dispose.
Moving the session tree now compares the loaded panel form with the new
branch's draft and rebuilds it, and its draft recorder, when they differ,
so answers rolled back on the old branch are neither shown nor submitted.
Focus and expiry clocks are left alone.
@GaganSD

GaganSD commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

@greptile-apps please re-review

@GaganSD
GaganSD merged commit 97ac225 into main Nov 18, 2026
9 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant