Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
a80a7c6
feat(ask): add queued, deferred and expired result contract
GaganSD Nov 17, 2026
c1216c8
feat(ask): add expiry and background config keys
GaganSD Nov 17, 2026
f7f9860
feat(ask): gate async schema fields and enforce token ceilings
GaganSD Nov 17, 2026
8b0333b
feat(ask): add session journal entries and branch replay
GaganSD Nov 17, 2026
3c18c61
feat(ask): journal forms and recover interrupted ones
GaganSD Nov 17, 2026
3090da0
docs(ask): describe the async contract and session journal
GaganSD Nov 17, 2026
b3d774a
feat(ask): add answer-later and panel-focus keymaps
GaganSD Nov 17, 2026
23ea980
feat(ask): journal panel visibility and order the panel queue
GaganSD Nov 17, 2026
73ee3fe
feat(ask): add pure panel ownership and delivery planning
GaganSD Nov 17, 2026
579c7d0
feat(ask): queue forms in a non-modal panel with defer and late delivery
GaganSD Nov 17, 2026
ad9311f
feat(ask): register the background field and add its settings toggle
GaganSD Nov 17, 2026
56af54f
docs(ask): describe the panel, answer later and background delivery
GaganSD Nov 17, 2026
d288b53
feat(ask): add pure expiry clock and fallback rules
GaganSD Nov 17, 2026
189c694
feat(ask): journal countdown stops and corrections to expired forms
GaganSD Nov 17, 2026
9e01324
feat(ask): count down visible forms and apply declared fallbacks
GaganSD Nov 17, 2026
60d9845
docs(ask): describe expiry, the stopped clock and late override
GaganSD Nov 17, 2026
d5c59f4
feat(ask): skip one question and cancel with a comment
GaganSD Nov 17, 2026
6756036
docs(ask): describe skip and cancel with a comment
GaganSD Nov 17, 2026
f9167ed
fix(ask): retry a wake that never started
GaganSD Nov 17, 2026
527e5ff
fix(ask): deliver an answer whose tool result never landed
GaganSD Nov 17, 2026
583eeb6
docs(ask): report the default token footprint
GaganSD Nov 17, 2026
3a95ae9
fix(ask): arm the expiry clock only after a notification succeeds
GaganSD Nov 17, 2026
a36487b
refactor(ask): drop the unused delivery marker and honour the stopped…
GaganSD Nov 17, 2026
b00b8d4
docs(ask): describe the async release in the changelog
GaganSD Nov 17, 2026
6bf1f08
fix(ask): retry an adopted answer whose wake never starts
GaganSD Nov 17, 2026
11e9a65
docs(ask): cite token estimates in the changelog footprint
GaganSD Nov 17, 2026
0301a15
fix(ask): keep editor text in recovered drafts
GaganSD Nov 17, 2026
44eb6aa
fix(ask): rebuild a retained form after a tree move
GaganSD Nov 17, 2026
2ca22ca
fix(ask): do not renotify a form rebuilt after a tree move
GaganSD Nov 17, 2026
ad98535
fix(ask): flush a blocking form's draft on shutdown
GaganSD Nov 17, 2026
f31c17a
test(ask): split background coverage by lifecycle responsibility
GaganSD Nov 18, 2026
476b105
fix(ask): retain panel controllers while temporarily hidden
GaganSD Nov 18, 2026
ddb0528
fix(ask): require journal writes before acknowledging forms
GaganSD Nov 18, 2026
e6091dc
fix(ask): retain adopted outcomes until branch-proven delivery
GaganSD Nov 18, 2026
d86bfff
refactor(ask): use canonical host boundary contracts
GaganSD Nov 18, 2026
9ed4b6e
refactor(ask): remove the redundant shipped-feature mask
GaganSD Nov 18, 2026
44b733a
docs(ask): document durable acknowledgements and retained drafts
GaganSD Nov 18, 2026
4aa96d9
refactor(ask): remove unused background extension points
GaganSD Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions pi-ask/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
92 changes: 83 additions & 9 deletions pi-ask/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,43 +32,117 @@ 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

| Command | What it does |
| --- | --- |
| `/answer` | Turn the latest completed assistant message into a form |
| `/ask-settings` | Settings overlay. `?` inside a form opens the same overlay |
| `/ask-panel` | Show the waiting questions, and 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.
61 changes: 61 additions & 0 deletions pi-ask/scripts/footprint.ts
Original file line number Diff line number Diff line change
@@ -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),
};
}
45 changes: 17 additions & 28 deletions pi-ask/scripts/token-report.mjs
Original file line number Diff line number Diff line change
@@ -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);
2 changes: 2 additions & 0 deletions pi-ask/skills/ask-user/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
13 changes: 4 additions & 9 deletions pi-ask/src/ask-tool-helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,15 +48,14 @@ export function invalidPayloadResponse(
}

export function nonInteractiveResponse(
state: ReturnType<typeof createInitialState>
state: ReturnType<typeof createInitialState>,
details: AskResult = toAskResult(state, "unavailable")
) {
return {
content: [
{ type: "text" as const, text: formatNonInteractiveMessage(state) },
],
details: {
...toAskResult(state, "unavailable"),
},
details,
};
}

Expand Down Expand Up @@ -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
);
Expand Down
Loading
Loading